clinicaltrialsgov-mcp-server

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

Descripción general

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

Related MCP server: Healthcare MCP Server

Herramientas

clinicaltrials_search_studies

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

• Consultas de texto completo y específicas por campo (condición, intervención, patrocinador, ubicación, título, resultado)

• Filtros de estado y fase con valores de enumeración tipados

• Filtrado de proximidad geográfica por coordenadas y distancia

• Soporte avanzado de expresiones Essie AREA[] para consultas complejas

• Selección de campos para reducir el tamaño de la carga útil (los registros completos son de ~70KB cada uno)

• Paginación con tokens de cursor, ordenación 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 de resumen opcional condensa los resultados completos (~200KB) a metadatos esenciales (~5KB por estudio)

• Procesamiento por lotes de múltiples IDs NCT por llamada con informes de éxito parcial

• Seguimiento separado de estudios sin resultados y errores de recuperación

clinicaltrials_find_eligible

Empareja un perfil de paciente con ensayos de reclutamiento elegibles.

• Toma la edad, sexo, condiciones y ubicación como datos demográficos del paciente

• Crea consultas de API optimizadas con filtros demográficos (rango de edad, sexo, voluntarios sanos)

• Devuelve estudios con campos de elegibilidad y ubicación para que el llamador los evalúe

• Proporciona sugerencias prácticas 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 controladores lanzan, el framework captura y clasifica

• Transporte dual: stdio y HTTP transmitible 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 requieren autenticación ni claves de API

• Reintento con retroceso exponencial (3 intentos) y limitación de tasa (~1 req/seg)

• Detección de errores HTML y fábricas de errores estructuradas

Primeros pasos

Instancia pública alojada

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

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

Autoalojado / Local

Agrégalo 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 transmitible:

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

Requisitos previos

• Bun v1.2.0 o superior (o Node.js >= 22.0.0)

Instalación

1. Clona el repositorio:

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

2. Navega al directorio:

   cd clinicaltrialsgov-mcp-server

3. Instala las dependencias:

   bun install

Configuración

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

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 en modo de desarrollo (con watch):

  bun run dev:http     # or dev:stdio

• Ejecuta comprobaciones 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

Guía de desarrollo

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

• Los controladores lanzan, el framework captura: no uses try/catch en la lógica de la herramienta

• Usa ctx.log para el registro con alcance de solicitud, no llamadas a console

• Registra nuevas herramientas y recursos en los archivos barril index.ts

Contribución

Las incidencias y las solicitudes de extracción (pull requests) son bienvenidas. Ejecuta las comprobaciones antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0: consulta LICENSE para obtener más detalles.