ClinicalTrials.gov

Buscar y recuperar datos de ensayos clínicos de la API oficial de ClinicalTrials.gov.

Documentación

clinicaltrialsgov-mcp-server

Busca ensayos en ClinicalTrials.gov, recupera detalles y resultados de estudios, y empareja pacientes con ensayos elegibles mediante MCP. STDIO o HTTP transmisible.

7 Herramientas • 1 Recurso • 1 Prompt

Servidor público alojado: https://clinicaltrials.caseyjhand.com/mcp

Descripción general

Siete herramientas para buscar, descubrir, analizar y emparejar ensayos clínicos:

Nombre de la herramienta	Descripción
`clinicaltrials_search_studies`	Busca estudios con consultas de texto completo, filtros, paginación, ordenamiento y selección de campos.
`clinicaltrials_get_study_record`	Obtiene un solo estudio por ID de NCT. Devuelve el registro completo: protocolo, elegibilidad, resultados, brazos, intervenciones, contactos y ubicaciones.
`clinicaltrials_get_study_count`	Obtiene el recuento total de estudios para una consulta sin recuperar datos. Estadísticas rápidas y desgloses.
`clinicaltrials_get_field_values`	Descubre valores válidos para campos de la API (estado, fase, tipo de estudio, etc.) con recuentos por valor.
`clinicaltrials_get_field_definitions`	Explora el árbol de campos del modelo de datos de estudios: nombres de piezas, tipos, anidamiento. Admite navegación por subárboles y búsqueda por palabras clave.
`clinicaltrials_get_study_results`	Extrae resultados, eventos adversos, flujo de participantes y datos basales de estudios completados. El modo resumen opcional reduce cargas de ~200KB a ~5KB; `outcomeLimit` / `adverseEventLimit` limitan el modo completo sin abandonarlo.
`clinicaltrials_find_eligible`	Empareja demografía de pacientes y condiciones con ensayos elegibles en reclutamiento. Proporciona edad, sexo, condiciones y ubicación para encontrar estudios con criterios de elegibilidad, contactos y ubicaciones de reclutamiento coincidentes.

Recurso	Descripción
`clinicaltrials://{nctId}`	Obtiene un solo estudio de ensayo clínico por ID de NCT. Protocolo JSON con ubicaciones/resultados/referencias limitados y resultados reemplazados por recuentos; las omisiones se informan con la herramienta que las recupera.

Prompt	Descripción
`analyze_trial_landscape`	Flujo de trabajo adaptable para análisis de panorama de ensayos basado en datos usando herramientas de recuento y búsqueda.

Herramientas

`clinicaltrials_search_studies`

Herramienta de búsqueda principal con capacidades completas de consulta de ClinicalTrials.gov.

Consultas de texto completo y específicas de campo (condición, intervención, patrocinador, ubicación, título, resultado)
Filtros de estado y fase con valores de enumeración tipados
Filtrado por proximidad geográfica mediante coordenadas y distancia
Soporte avanzado de expresiones Essie AREA[] para consultas complejas
Resultados de índice compactos por defecto; pasa fields para una proyección de fidelidad completa de hojas específicas (un registro completo individual es ~70KB — obtén uno con get_study_record)
Paginación con tokens de cursor, ordenamiento por cualquier campo

`clinicaltrials_get_study_results`

Obtiene datos de resultados publicados para estudios completados.

Medidas de resultados con estadísticas, eventos adversos, flujo de participantes, características basales
Filtrado a nivel de sección (solicita solo los datos que necesitas)
El modo resumen opcional condensa resultados completos (~200KB) a metadatos esenciales (~5KB por estudio)
Procesamiento por lotes de múltiples ID de NCT por llamada con informe de éxito parcial
Seguimiento separado de estudios sin resultados y errores de recuperación

`clinicaltrials_find_eligible`

Empareja un perfil de paciente con ensayos elegibles en reclutamiento.

Toma edad, sexo, condiciones y ubicación como demografía del paciente
Construye consultas de API optimizadas con filtros demográficos (rango de edad, sexo, voluntarios sanos)
Reordena los resultados para que los estudios cuya propia condición coincide con una condición solicitada aparezcan por encima de coincidencias tangenciales de la búsqueda difusa de condiciones ascendente
Devuelve estudios con campos de elegibilidad y ubicación para que el llamador los evalúe
Limita cada candidato a los sitios que coinciden con la ubicación solicitada (limitado por locationLimit) en lugar de cada sitio que el estudio registra a nivel mundial, agrega el sitio de reclutamiento más cercano cuando ninguno de los coincidentes está abierto, y revela lo que se omitió
Proporciona sugerencias accionables cuando no hay estudios coincidentes (ampliar condiciones, ajustar filtros)

Características

Construido sobre @cyanheads/mcp-ts-core:

Definiciones declarativas de herramientas/recursos/prompts con esquemas Zod y funciones de formato
Manejo de errores unificado: los manejadores lanzan, el marco captura y clasifica
Transporte dual: stdio y HTTP transmisible desde la misma base de código
Autenticación conectable (none, jwt, oauth) para transporte HTTP
Registro estructurado con rastreo opcional de OpenTelemetry

Específico de ClinicalTrials.gov:

Cliente con seguridad de tipos para la API REST v2 de ClinicalTrials.gov
API pública: no se requiere autenticación ni claves de API
Reintento con retroceso exponencial (3 intentos) y limitación de velocidad (~1 solicitud/seg)
Detección de errores HTML y fábricas de errores estructurados

Primeros pasos

Instancia pública alojada

Hay una instancia pública disponible en https://clinicaltrials.caseyjhand.com/mcp — no se requiere instalación. Apunta cualquier cliente MCP a ella mediante HTTP transmisible:

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

Autoalojado / Local

Agrega a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json):

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

O para HTTP transmisible:

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

Requisitos previos

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

Instalación

Clona el repositorio:

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

Navega al directorio:
```
cd clinicaltrialsgov-mcp-server
```
Instala las dependencias:
```
bun install
```

Configuración

Toda la configuración es opcional: el servidor funciona con valores predeterminados y sin claves de API.

Variable	Descripción	Predeterminado
`CT_API_BASE_URL`	URL base de la API de ClinicalTrials.gov.	`https://clinicaltrials.gov/api/v2`
`CT_REQUEST_TIMEOUT_MS`	Tiempo de espera por solicitud en milisegundos.	`30000`
`CT_MAX_PAGE_SIZE`	Límite máximo de tamaño de página.	`200`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` o `http`.	`stdio`
`MCP_HTTP_PORT`	Puerto para el servidor HTTP.	`3010`
`MCP_AUTH_MODE`	Modo de autenticación: `none`, `jwt` o `oauth`.	`none`
`MCP_LOG_LEVEL`	Nivel de registro (RFC 5424).	`info`
`LOGS_DIR`	Directorio para archivos de registro (solo Node.js).	`<project-root>/logs`
`OTEL_ENABLED`	Habilita el rastreo de OpenTelemetry.	`false`

Ejecución del servidor

Desarrollo local

Compila y ejecuta la versión de producción:

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

Ejecuta verificaciones y pruebas:

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

Estructura del proyecto

Directorio	Propósito
`src/mcp-server/tools/`	Definiciones de herramientas (`*.tool.ts`).
`src/mcp-server/resources/`	Definiciones de recursos (`*.resource.ts`).
`src/mcp-server/prompts/`	Definiciones de prompts (`*.prompt.ts`).
`src/services/clinical-trials/`	Cliente de API de ClinicalTrials.gov y tipos.
`src/config/`	Análisis y validación de variables de entorno con Zod.
`tests/`	Pruebas unitarias y de integración.

Guía de desarrollo

Consulta CLAUDE.md para pautas de desarrollo y reglas arquitectónicas. La versión corta:

Los manejadores lanzan, el marco captura — sin try/catch en la lógica de herramientas
Usa ctx.log para registro con ámbito de solicitud, sin llamadas a console
Registra nuevas herramientas y recursos en los archivos de barril index.ts

Contribuciones

Se aceptan problemas y solicitudes de extracción. Ejecuta las verificaciones antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0 — consulta LICENSE para más detalles.