io.github.cyanheads/clinicaltrialsgov-mcp-server

Official

by cyanheads · TypeScript

Search ClinicalTrials.gov — find studies, retrieve results, match patients to eligible trials.

Search and retrieve clinical trial data to match patients with eligible studies.

Topics

mcpmcp-serverai-agentclinical-trialseligibility-criteriahealth-techmodel-context-protocolpatient-matchingtypescriptclinicaltrials-govtrial-finderbioinformaticsresearch-toolscyanheads

README.md11 KBView on GitHub

<div align="center"> <h1>clinicaltrialsgov-mcp-server</h1> <p><b>Search ClinicalTrials.gov trials, retrieve study details and results, and match patients to eligible trials via MCP. STDIO or Streamable HTTP.</b> <div>7 Tools • 1 Resource • 1 Prompt</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://clinicaltrials.caseyjhand.com/mcp

</div>

Overview

Seven tools for searching, discovering, analyzing, and matching clinical trials:

Tool Name	Description
`clinicaltrials_search_studies`	Search studies with full-text queries, filters, pagination, sorting, and field selection.
`clinicaltrials_get_study_record`	Fetch a single study by NCT ID. Returns the full record: protocol, eligibility, outcomes, arms, interventions, contacts, and locations.
`clinicaltrials_get_study_count`	Get total study count for a query without fetching data. Fast statistics and breakdowns.
`clinicaltrials_get_field_values`	Discover valid values for API fields (status, phase, study type, etc.) with per-value counts.
`clinicaltrials_get_field_definitions`	Browse the study data model field tree — piece names, types, nesting. Supports subtree navigation and keyword search.
`clinicaltrials_get_study_results`	Extract outcomes, adverse events, participant flow, and baseline from completed studies. Optional summary mode reduces ~200KB payloads to ~5KB.
`clinicaltrials_find_eligible`	Match patient demographics and conditions to eligible recruiting trials. Provide age, sex, conditions, and location to find studies with matching eligibility criteria, contacts, and recruiting locations.

Resource	Description
`clinicaltrials://{nctId}`	Fetch a single clinical trial study by NCT ID. Full JSON.

Prompt	Description
`analyze_trial_landscape`	Adaptable workflow for data-driven trial landscape analysis using count + search tools.

Tools

`clinicaltrials_search_studies`

Primary search tool with full ClinicalTrials.gov query capabilities.

Full-text and field-specific queries (condition, intervention, sponsor, location, title, outcome)
Status and phase filters with typed enum values
Geographic proximity filtering by coordinates and distance
Advanced AREA[] Essie expression support for complex queries
Compact index results by default; pass fields for a full-fidelity projection of specific leaves (a full single record is ~70KB — fetch one with get_study_record)
Pagination with cursor tokens, sorting by any field

`clinicaltrials_get_study_results`

Fetch posted results data for completed studies.

Outcome measures with statistics, adverse events, participant flow, baseline characteristics
Section-level filtering (request only the data you need)
Optional summary mode condenses full results (~200KB) to essential metadata (~5KB per study)
Batch multiple NCT IDs per call with partial-success reporting
Separate tracking of studies without results and fetch errors

`clinicaltrials_find_eligible`

Match a patient profile to eligible recruiting trials.

Takes age, sex, conditions, and location as patient demographics
Builds optimized API queries with demographic filters (age range, sex, healthy volunteers)
Re-ranks results so studies whose own condition matches a requested condition surface above tangential matches from the upstream fuzzy condition search
Returns studies with eligibility and location fields for the caller to evaluate
Provides actionable hints when no studies match (broaden conditions, adjust filters)

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool/resource/prompt definitions with Zod schemas and format functions
Unified error handling — handlers throw, framework catches and classifies
Dual transport: stdio and Streamable HTTP from the same codebase
Pluggable auth (none, jwt, oauth) for HTTP transport
Structured logging with optional OpenTelemetry tracing

ClinicalTrials.gov-specific:

Type-safe client for the ClinicalTrials.gov REST API v2
Public API — no authentication or API keys required
Retry with exponential backoff (3 attempts) and rate limiting (~1 req/sec)
HTML error detection and structured error factories

Getting Started

Public Hosted Instance

A public instance is available at https://clinicaltrials.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

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

Self-Hosted / Local

Add to your MCP client config (e.g., claude_desktop_config.json):

json

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

Or for Streamable HTTP:

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

Prerequisites

Bun v1.3.0 or higher (or Node.js >= 24.0.0)

Installation

Clone the repository:

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

Navigate into the directory:
sh
```
cd clinicaltrialsgov-mcp-server
```
Install dependencies:
sh
```
bun install
```

Configuration

All configuration is optional — the server works with defaults and no API keys.

Variable	Description	Default
`CT_API_BASE_URL`	ClinicalTrials.gov API base URL.	`https://clinicaltrials.gov/api/v2`
`CT_REQUEST_TIMEOUT_MS`	Per-request timeout in milliseconds.	`30000`
`CT_MAX_PAGE_SIZE`	Maximum page size cap.	`200`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`OTEL_ENABLED`	Enable OpenTelemetry tracing.	`false`

Running the Server

Local Development

Build and run the production version:

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

Run checks and tests:

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

Project Structure

Directory	Purpose
`src/mcp-server/tools/`	Tool definitions (`*.tool.ts`).
`src/mcp-server/resources/`	Resource definitions (`*.resource.ts`).
`src/mcp-server/prompts/`	Prompt definitions (`*.prompt.ts`).
`src/services/clinical-trials/`	ClinicalTrials.gov API client and types.
`src/config/`	Environment variable parsing and validation with Zod.
`tests/`	Unit and integration tests.

Development Guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, no console calls
Register new tools and resources in the index.ts barrel files

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Configuration

Environment variables

CT_API_BASE_URLdefault https://clinicaltrials.gov/api/v2

ClinicalTrials.gov API base URL.

CT_REQUEST_TIMEOUT_MSdefault 30000

Per-request timeout in milliseconds.

CT_MAX_PAGE_SIZEdefault 200

Maximum page size cap.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "clinicaltrialsgov-mcp-server@2.8.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "CT_API_BASE_URL": "https://clinicaltrials.gov/api/v2",
        "CT_REQUEST_TIMEOUT_MS": "30000",
        "CT_MAX_PAGE_SIZE": "200",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}