cyanheads/clinicaltrialsgov-mcp-server

Tools

Seven tools for working with ClinicalTrials.gov data:

clinicaltrials_search_studies

Search for clinical trials using free-text queries and filters.

• Full-text search plus specialized condition, intervention, and sponsor queries targeting specific API indexes
• Typed enum filters for study status and phase (single value or array)
• Geographic proximity filtering by coordinates and distance
• Advanced filtering with ClinicalTrials.gov's AREA[] syntax
• Pagination (up to 200 per page), sorting, and field selection

clinicaltrials_get_study

Fetch one or more clinical trials by NCT ID, with full data or concise summaries.

• Batch fetch up to 5 studies at once
• Full data includes protocol sections, results, adverse events, outcome measures, eligibility, and locations
• Partial success reporting when some studies in a batch fail

clinicaltrials_analyze_trends

Aggregate statistics across up to 5,000 studies by status, country, sponsor, phase, year, month, study type, or intervention type.

• Combine multiple analysis types in a single request
• Filter to focus on specific subsets
• Returns counts and top categories (percentages omitted for phase breakdowns, where multi-phase studies make the denominator ambiguous)

clinicaltrials_compare_studies

Compare 2-5 studies side-by-side across eligibility, design, interventions, outcomes, sponsors, and locations.

• Configurable comparison fields — compare everything or focus on specific aspects
• Handles partial failures if some studies can't be fetched

clinicaltrials_find_eligible_studies

Match a patient profile (age, sex, conditions, location) to eligible clinical trials.

• Hard filters on age, sex, healthy volunteer status, and country — ineligible studies are excluded entirely
• Condition token overlap used as a false-positive gate (studies with zero relevance to the patient's conditions are excluded)
• Results sorted by location proximity: city match → state match → country-only, then by number of nearby sites
• Returns a summary of why each study is a potential match

clinicaltrials_get_study_results

Fetch results data (outcomes, adverse events, participant flow, baseline characteristics) for completed studies.

• Section-level filtering — request only the sections you need
• Batch up to 5 studies per request
• Reports which studies lack results or failed to fetch
• Includes statistical analyses (p-values, methods) with outcome data

clinicaltrials_get_field_values

Look up valid enum values for any ClinicalTrials.gov API field, with study counts per value.

• Sorted by frequency
• Useful for exploring OverallStatus, Phase, InterventionType, StudyType, and other fields before constructing filters

Features

Built on mcp-ts-template:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified McpError error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2
• Structured logging (Pino) with optional OpenTelemetry tracing
• Typed DI container with Token<T> phantom branding
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

ClinicalTrials.gov-specific:

• Type-safe client for the ClinicalTrials.gov v2 API
• Tools for search, filtering, statistical aggregation, and patient matching
• Automatic cleaning and simplification of API responses for agent consumption

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:

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

Self-Hosted / Local

Add the following to your MCP Client configuration file (e.g., cline_mcp_settings.json).

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

Or for Streamable HTTP:

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3017

Prerequisites

• Bun v1.2.0 or higher.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd clinicaltrialsgov-mcp-server

3. Install dependencies:

bun install

Configuration

All configuration is centralized and validated at startup in src/config/index.ts. Key environment variables in your .env file include:

Running the server

Local Development

• Build and run the production version:

  # One-time build
  bun rebuild
  
  # Run the built server
  bun start:http
  # or
  bun start:stdio
  

• Run checks and tests:

  bun devcheck # Lints, formats, type-checks, and more
  bun test # Runs the test suite
  

Cloudflare Workers

1. Build the Worker bundle:

bun build:worker

2. Run locally with Wrangler:

bun deploy:dev

3. Deploy to Cloudflare:

   bun deploy:prod
   

Project structure

Development guide

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

• Logic throws McpError, handlers catch — no try/catch in tool logic
• Pass RequestContext through the call stack for logging and tracing
• Register new tools and resources in the index.ts barrel files

Contributing

Issues and pull requests are welcome! If you plan to contribute, please run the local checks and tests before submitting your PR.

bun run devcheck
bun test

License

This project is licensed under the Apache 2.0 License. See the file for details.