clinicaltrialsgov-mcp-server

Öffentlich gehosteter Server: https://clinicaltrials.caseyjhand.com/mcp

Übersicht

Sieben Tools zum Suchen, Entdecken, Analysieren und Abgleichen klinischer Studien:

Related MCP server: Healthcare MCP Server

Tools

clinicaltrials_search_studies

Primäres Such-Tool mit vollem Funktionsumfang für ClinicalTrials.gov-Abfragen.

• Volltext- und feldspezifische Abfragen (Erkrankung, Intervention, Sponsor, Standort, Titel, Ergebnis)

• Status- und Phasenfilter mit typisierten Enum-Werten

• Geografische Umkreissuche nach Koordinaten und Entfernung

• Erweiterte Unterstützung für AREA[] Essie-Ausdrücke für komplexe Abfragen

• Feldauswahl zur Reduzierung der Payload-Größe (vollständige Datensätze sind jeweils ~70KB groß)

• Paginierung mit Cursor-Tokens, Sortierung nach jedem Feld

clinicaltrials_get_study_results

Abrufen veröffentlichter Ergebnisdaten für abgeschlossene Studien.

• Ergebnismessungen mit Statistiken, unerwünschten Ereignissen, Teilnehmerfluss, Basismerkmalen

• Filterung auf Abschnittsebene (fordern Sie nur die Daten an, die Sie benötigen)

• Optionaler Zusammenfassungsmodus verdichtet vollständige Ergebnisse (~200KB) auf wesentliche Metadaten (~5KB pro Studie)

• Batch-Verarbeitung mehrerer NCT-IDs pro Aufruf mit Berichterstattung bei Teilerfolgen

• Separate Nachverfolgung von Studien ohne Ergebnisse und Abruffehlern

clinicaltrials_find_eligible

Abgleich eines Patientenprofils mit geeigneten rekrutierenden Studien.

• Verwendet Alter, Geschlecht, Erkrankungen und Standort als Patientendemografie

• Erstellt optimierte API-Abfragen mit demografischen Filtern (Altersbereich, Geschlecht, gesunde Freiwillige)

• Gibt Studien mit Eignungs- und Standortfeldern zur Auswertung durch den Aufrufer zurück

• Bietet umsetzbare Hinweise, wenn keine Studien übereinstimmen (Erkrankungen erweitern, Filter anpassen)

Funktionen

Aufgebaut auf @cyanheads/mcp-ts-core:

• Deklarative Tool-/Ressourcen-/Prompt-Definitionen mit Zod-Schemas und Formatierungsfunktionen

• Einheitliche Fehlerbehandlung — Handler werfen Fehler, das Framework fängt sie ab und klassifiziert sie

• Dualer Transport: stdio und Streamable HTTP aus derselben Codebasis

• Steckbare Authentifizierung (none, jwt, oauth) für HTTP-Transport

• Strukturierte Protokollierung mit optionalem OpenTelemetry-Tracing

ClinicalTrials.gov-spezifisch:

• Typsicherer Client für die ClinicalTrials.gov REST API v2

• Öffentliche API — keine Authentifizierung oder API-Schlüssel erforderlich

• Wiederholungsversuche mit exponentiellem Backoff (3 Versuche) und Ratenbegrenzung (~1 Anfrage/Sek.)

• HTML-Fehlererkennung und strukturierte Fehler-Factories

Erste Schritte

Öffentlich gehostete Instanz

Eine öffentliche Instanz ist unter https://clinicaltrials.caseyjhand.com/mcp verfügbar — keine Installation erforderlich. Verweisen Sie jeden MCP-Client über Streamable HTTP darauf:

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

Selbst gehostet / Lokal

Hinzufügen zur Konfiguration Ihres MCP-Clients (z. B. claude_desktop_config.json):

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

Oder für Streamable HTTP:

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

Voraussetzungen

• Bun v1.2.0 oder höher (oder Node.js >= 22.0.0)

Installation

1. Repository klonen:

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

2. In das Verzeichnis navigieren:

   cd clinicaltrialsgov-mcp-server

3. Abhängigkeiten installieren:

   bun install

Konfiguration

Alle Konfigurationen sind optional — der Server funktioniert mit Standardwerten und ohne API-Schlüssel.

Server ausführen

Lokale Entwicklung

• Produktionsversion erstellen und ausführen:

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

• Im Entwicklungsmodus ausführen (mit Watch):

  bun run dev:http     # or dev:stdio

• Prüfungen und Tests ausführen:

  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

Projektstruktur

Entwicklungsleitfaden

Siehe CLAUDE.md für Entwicklungsrichtlinien und architektonische Regeln. Die Kurzfassung:

• Handler werfen Fehler, das Framework fängt sie ab — kein try/catch in der Tool-Logik

• Verwenden Sie ctx.log für anfragebezogene Protokollierung, keine console-Aufrufe

• Registrieren Sie neue Tools und Ressourcen in den index.ts-Barrel-Dateien

Mitwirken

Fehlermeldungen und Pull Requests sind willkommen. Führen Sie vor dem Einreichen die Prüfungen aus:

bun run devcheck
bun run test

Lizenz

Apache-2.0 — siehe LICENSE für Details.