ClinicalTrials.gov

Pesquise e recupere dados de ensaios clínicos da API oficial do ClinicalTrials.gov.

Documentação

clinicaltrialsgov-mcp-server

Pesquise ensaios clínicos no ClinicalTrials.gov, recupere detalhes e resultados de estudos e corresponda pacientes a ensaios elegíveis via MCP. STDIO ou Streamable HTTP.

7 Ferramentas • 1 Recurso • 1 Prompt

Servidor Público Hospedado: https://clinicaltrials.caseyjhand.com/mcp

Visão Geral

Sete ferramentas para buscar, descobrir, analisar e corresponder ensaios clínicos:

Nome da Ferramenta	Descrição
`clinicaltrials_search_studies`	Pesquise estudos com consultas de texto completo, filtros, paginação, ordenação e seleção de campos.
`clinicaltrials_get_study_record`	Busque um único estudo pelo NCT ID. Retorna o registro completo: protocolo, elegibilidade, desfechos, braços, intervenções, contatos e locais.
`clinicaltrials_get_study_count`	Obtenha a contagem total de estudos para uma consulta sem buscar dados. Estatísticas rápidas e detalhamentos.
`clinicaltrials_get_field_values`	Descubra valores válidos para campos da API (status, fase, tipo de estudo, etc.) com contagens por valor.
`clinicaltrials_get_field_definitions`	Navegue pela árvore de campos do modelo de dados do estudo — nomes de peças, tipos, aninhamento. Suporta navegação por subárvore e busca por palavras-chave.
`clinicaltrials_get_study_results`	Extraia desfechos, eventos adversos, fluxo de participantes e linha de base de estudos concluídos. O modo de resumo opcional reduz cargas de ~200KB para ~5KB; `outcomeLimit` / `adverseEventLimit` limitam o modo completo sem abandoná-lo.
`clinicaltrials_find_eligible`	Corresponda dados demográficos e condições de pacientes a ensaios elegíveis em recrutamento. Forneça idade, sexo, condições e localização para encontrar estudos com critérios de elegibilidade, contatos e locais de recrutamento correspondentes.

Recurso	Descrição
`clinicaltrials://{nctId}`	Busque um único estudo de ensaio clínico pelo NCT ID. Protocolo JSON com locais/desfechos/referências limitados e resultados substituídos por contagens; omissões relatadas com a ferramenta que as recupera.

Prompt	Descrição
`analyze_trial_landscape`	Fluxo de trabalho adaptável para análise de cenário de ensaios orientada por dados usando ferramentas de contagem + busca.

Ferramentas

`clinicaltrials_search_studies`

Ferramenta de busca principal com capacidades completas de consulta do ClinicalTrials.gov.

Consultas de texto completo e específicas por campo (condição, intervenção, patrocinador, localização, título, desfecho)
Filtros de status e fase com valores enumerados tipados
Filtragem por proximidade geográfica usando coordenadas e distância
Suporte a expressões avançadas AREA[] Essie para consultas complexas
Resultados de índice compactos por padrão; passe fields para uma projeção de fidelidade total de folhas específicas (um único registro completo tem ~70KB — busque um com get_study_record)
Paginação com tokens de cursor, ordenação por qualquer campo

`clinicaltrials_get_study_results`

Busque dados de resultados publicados para estudos concluídos.

Medidas de desfecho com estatísticas, eventos adversos, fluxo de participantes, características de linha de base
Filtragem por nível de seção (solicite apenas os dados necessários)
Modo de resumo opcional condensa resultados completos (~200KB) em metadados essenciais (~5KB por estudo)
Lote de múltiplos NCT IDs por chamada com relatório de sucesso parcial
Rastreamento separado de estudos sem resultados e erros de busca

`clinicaltrials_find_eligible`

Corresponda um perfil de paciente a ensaios elegíveis em recrutamento.

Aceita idade, sexo, condições e localização como dados demográficos do paciente
Constrói consultas otimizadas de API com filtros demográficos (faixa etária, sexo, voluntários saudáveis)
Reordena resultados para que estudos cuja própria condição corresponda a uma condição solicitada apareçam acima de correspondências tangenciais da busca difusa de condições upstream
Retorna estudos com campos de elegibilidade e localização para o chamador avaliar
Limita cada candidato aos locais que correspondem à localização solicitada (limitado por locationLimit) em vez de todos os locais que o estudo registra mundialmente, adiciona o local de recrutamento mais próximo quando nenhum dos correspondentes está aberto e divulga o que foi omitido
Fornece dicas acionáveis quando nenhum estudo corresponde (ampliar condições, ajustar filtros)

Recursos

Construído sobre @cyanheads/mcp-ts-core:

Definições declarativas de ferramentas/recursos/prompts com esquemas Zod e funções de formato
Tratamento de erros unificado — manipuladores lançam, o framework captura e classifica
Transporte duplo: stdio e Streamable HTTP a partir do mesmo código-base
Autenticação plugável (none, jwt, oauth) para transporte HTTP
Registro estruturado com rastreamento OpenTelemetry opcional

Específico do ClinicalTrials.gov:

Cliente type-safe para a API REST v2 do ClinicalTrials.gov
API pública — sem autenticação ou chaves de API necessárias
Repetição com backoff exponencial (3 tentativas) e limitação de taxa (~1 req/seg)
Detecção de erros HTML e fábricas de erros estruturados

Começando

Instância Pública Hospedada

Uma instância pública está disponível em https://clinicaltrials.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "streamable-http",
      "url": "https://clinicaltrials.caseyjhand.com/mcp"
    }
  }
}

Auto-hospedado / Local

Adicione à configuração do seu cliente MCP (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["clinicaltrialsgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Ou para Streamable HTTP:

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

Pré-requisitos

Bun v1.3.0 ou superior (ou Node.js >= 24.0.0)

Instalação

Clone o repositório:

git clone https://github.com/cyanheads/clinicaltrialsgov-mcp-server.git

Navegue para o diretório:
```
cd clinicaltrialsgov-mcp-server
```
Instale as dependências:
```
bun install
```

Configuração

Toda a configuração é opcional — o servidor funciona com padrões e sem chaves de API.

Variável	Descrição	Padrão
`CT_API_BASE_URL`	URL base da API do ClinicalTrials.gov.	`https://clinicaltrials.gov/api/v2`
`CT_REQUEST_TIMEOUT_MS`	Tempo limite por solicitação em milissegundos.	`30000`
`CT_MAX_PAGE_SIZE`	Limite máximo de tamanho de página.	`200`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` ou `http`.	`stdio`
`MCP_HTTP_PORT`	Porta para o servidor HTTP.	`3010`
`MCP_AUTH_MODE`	Modo de autenticação: `none`, `jwt` ou `oauth`.	`none`
`MCP_LOG_LEVEL`	Nível de registro (RFC 5424).	`info`
`LOGS_DIR`	Diretório para arquivos de registro (somente Node.js).	`<project-root>/logs`
`OTEL_ENABLED`	Habilitar rastreamento OpenTelemetry.	`false`

Executando o Servidor

Desenvolvimento Local

Compile e execute a versão de produção:

bun run build
bun run start:http   # or start:stdio

Execute verificações e testes:

bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Docker

docker build -t clinicaltrialsgov-mcp-server .
docker run -p 3010:3010 clinicaltrialsgov-mcp-server

Estrutura do Projeto

Diretório	Finalidade
`src/mcp-server/tools/`	Definições de ferramentas (`*.tool.ts`).
`src/mcp-server/resources/`	Definições de recursos (`*.resource.ts`).
`src/mcp-server/prompts/`	Definições de prompts (`*.prompt.ts`).
`src/services/clinical-trials/`	Cliente da API do ClinicalTrials.gov e tipos.
`src/config/`	Análise e validação de variáveis de ambiente com Zod.
`tests/`	Testes unitários e de integração.

Guia de Desenvolvimento

Consulte CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

Manipuladores lançam, o framework captura — sem try/catch na lógica de ferramentas
Use ctx.log para registro com escopo de solicitação, sem chamadas console
Registre novas ferramentas e recursos nos arquivos de barris index.ts

Contribuindo

Issues e pull requests são bem-vindos. Execute as verificações antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — consulte LICENSE para detalhes.