ClinicalTrials.gov

---

Tools

Seven tools for working with ClinicalTrials.gov data:

Tool Name	Description
clinicaltrials_search_studies	Searches for clinical studies using query terms, filters, pagination, and sorting. Includes geographic and enum-based filtering.
clinicaltrials_get_study	Fetches one or more clinical studies by their NCT IDs, returning either full data or concise summaries.
clinicaltrials_get_study_results	Fetches trial results data for completed studies — outcomes, adverse events, participant flow, and baseline characteristics.
clinicaltrials_get_field_values	Discovers valid enum values for any API field with study counts, enabling informed query construction.
clinicaltrials_analyze_trends	Performs statistical analysis on up to 5000 studies by status, country, sponsor, phase, year, month, study type, or intervention type.
clinicaltrials_compare_studies	Side-by-side comparison of 2-5 clinical studies across eligibility, design, interventions, outcomes, and sponsors.
clinicaltrials_find_eligible_studies	Matches patient profiles to eligible clinical trials, filtering by age, sex, conditions, and location. Returns studies sorted by proximity.

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

View detailed examples

---

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

View detailed examples

---

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)

View detailed examples

---

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

View detailed examples

---

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

View detailed examples

---

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:

Variable	Description	Default
MCP_TRANSPORT_TYPE	The transport to use: stdio or http.	http
MCP_HTTP_PORT	The port for the HTTP server.	3017
MCP_AUTH_MODE	Authentication mode: none, jwt, or oauth.	none
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv, cloudflare-r2, cloudflare-d1.	in-memory
OTEL_ENABLED	Set to true to enable OpenTelemetry.	false
MCP_LOG_LEVEL	The minimum level for logging (RFC 5424: debug, info, notice, warning, error, crit, alert, emerg).	info
MCP_AUTH_SECRET_KEY	**

---

README truncated. View full README on GitHub.