clinicaltrialsgov-mcp-server

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

Overview

Search 600K+ studies on ClinicalTrials.gov, the US National Library of Medicine's trial registry. Fetch full study records and posted results, discover fields and valid values, and match a patient's profile to recruiting trials. No API key required.

Tools

Resources

Prompts

Skills

Plugin installs load it from skills/; MCP clients that support the Skills extension read it as skill://clinicaltrialsgov-guide/SKILL.md. It also ships in the npm package and Docker image.

Related MCP server: ClinicalTrials.gov MCP Server

Capability reference

clinicaltrials_search_studies tool

• Free-text query plus field-specific conditionQuery / interventionQuery / locationQuery / sponsorQuery / titleQuery / outcomeQuery, statusFilter / phaseFilter enums (case and spacing variants accepted), advancedFilter (AREA[FieldName]value / RANGE[min, max]), and geoFilter (distance(lat,lon,radius) with a mi/km suffix); pageSize (default 10, no upper bound; above the server's per-page cap, 200 by default, a page is served at the cap with truncated / shown / cap), pageToken cursor, sort on up to 2 date or numeric fields (or @relevance)

• Each query and filter parameter also accepts its ClinicalTrials.gov REST name (query.cond or query_cond, filter.overallStatus, filter.geo, …), and condition, intervention, sponsor, phase, limit, and max_results work as aliases too

• Returns a compact per-study index by default (nctId, briefTitle, overallStatus, phases, enrollmentCount, hasResults, …); fields (PascalCase piece names, or full paths as clinicaltrials_get_field_definitions prints them) selects a full-fidelity projection — full records run ~70KB

• nctIds (up to 1000 entries, repeats collapsed) is served up to what fits one ClinicalTrials.gov request beside the other parameters — about 560 IDs on their own — with the rest returned unqueried in deferredNctIds, the same on every page of a walk

• Typed errors: blank_value, ids_not_found, field_invalid, enum_invalid, query_parse_error, geo_invalid, sort_invalid, page_token_invalid, request_too_long, rate_limited, retry_deadline_exceeded, upstream_timeout

clinicaltrials_get_study_record tool

• Full protocol record by nctId, with optional locationLimit, outcomeLimit / referenceLimit, and nearLocation (lat, lon, radiusMi) to bound and sort locations — none has an upper bound; a value past the list returns all of it, and 0 leaves that list out

• filtersApplied reports upstream totals when a cap trims a list; resultsSection is replaced by resultsSummary counts. Typed errors: study_not_found, rate_limited, retry_deadline_exceeded, upstream_timeout

clinicaltrials_get_study_count tool

• Same query and filter surface as clinicaltrials_search_studies, returning only totalCount — no study data fetched

• Typed errors: blank_value, field_invalid, enum_invalid, query_parse_error, request_too_long, rate_limited, retry_deadline_exceeded, upstream_timeout

clinicaltrials_get_field_values tool

• One or more PascalCase leaf fields (e.g. OverallStatus, Phase; a group such as LeadSponsor is refused with its leaf pieces named) — returns each field's type and top values with study counts (capped at 250 by the API), or min / max / avg for numeric and date fields and trueCount / falseCount for booleans

• STRING fields add their longest value; past 2,000 characters it is a preview flagged truncated, with the full length and a notice naming the clinicaltrials_search_studies call that returns the whole text. Free-text fields the API does not count distinct values on carry uniqueValuesCounted: false, marking their uniqueValuesCount of 0 as no count

• multiValued flags fields whose per-value counts can sum above the study total. Typed errors: blank_value, field_invalid, request_too_long, rate_limited, retry_deadline_exceeded, upstream_timeout

clinicaltrials_get_field_definitions tool

• mode: search (keyword query, limit default 20, no upper bound), drill (dot-notation path), or overview — resolves the PascalCase names accepted by fields, advancedFilter, sort (date and numeric fields), and clinicaltrials_get_field_values (leaf fields)

• Typed errors: blank_value, mode_mismatch, mode_requires, path_not_found, rate_limited, retry_deadline_exceeded, upstream_timeout

clinicaltrials_get_study_results tool

• Up to 20 distinct nctIds fetched per call, with any further IDs (up to 500 entries) returned in deferredNctIds; sections (outcomes, adverseEvents, participantFlow, baseline, moreInfo), summary to condense a result set that can exceed 500KB per study, and outcomeLimit / adverseEventLimit with resumable outcomeOffset / seriousEventOffset / otherEventOffset

• Per-study fetchErrors / studiesWithoutResults for IDs that fail on their own, while a failed batch request, a rate limit, the call's time budget, or a cancellation ends the call; canonicalNctId when an alias ID resolves to another study. Typed errors: blank_value, offset_not_applicable, rate_limited, retry_deadline_exceeded, upstream_timeout

clinicaltrials_find_eligible tool

• age (whole number 0–120) with optional ageUnit (years default, months, weeks, days) for infants and young children, sex (FEMALE / MALE / ALL), conditions[], location (country required, state / city optional; country synonyms such as USA, UK, and Czech Republic, and US state abbreviations, rank sites as the registry's spelling does), healthyVolunteer, recruitingOnly (default true), maxResults (or limit; no upper bound, each call returns at most 50, disclosing the rest via truncated / shown / cap and a replayable searchCriteria), locationLimit (no upper bound; a value past the matched sites returns them all)

• Matches on age, sex, location, recruitment status, and a fuzzy condition search; funnel reports match counts per filter stage, and a notice says inclusion/exclusion criteria were not checked (use clinicaltrials_get_study_record to review them)

• Typed errors: blank_value, field_invalid, enum_invalid, query_parse_error, request_too_long, rate_limited, retry_deadline_exceeded, upstream_timeout

clinicaltrials://{nctId} resource

• Full protocol record as application/json, with locations, secondary/other outcomes, and references each capped at 50 — fixed server-side, no arguments

• Results data is replaced by resultsSummary counts; truncated and filtersApplied disclose what was capped, with retrieval naming the tools that fetch the full data

• Typed errors: study_not_found, rate_limited, retry_deadline_exceeded, upstream_timeout

analyze_trial_landscape prompt

• Arguments: topic required; focusAreas (comma-separated) optional

• Returns one user message pointing the agent at the count, search, field-discovery, and results tools for a data-driven landscape analysis

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

ClinicalTrials.gov-specific:

• Type-safe client for the ClinicalTrials.gov REST API v2 — public, no authentication or API keys required

• Serialized request queue enforcing ClinicalTrials.gov's ~1 req/sec rate limit, with retry and exponential backoff on 429/5xx responses and HTML error pages, all inside one 50-second budget per tool call or resource read — a hung upstream ends the call with a typed retry_deadline_exceeded error before an MCP client's 60-second request timeout

• Auto-corrects field names passed to fields/sort (case, whitespace, legacy aliases like RecruitmentStatus → OverallStatus, a full path such as protocolSection.statusModule.overallStatus → OverallStatus in fields, a bare relevance → @relevance in sort) and the case of AREA[…] field names in advancedFilter and the query parameters (AREA[overallstatus] → AREA[OverallStatus]), index-only pieces and search areas included (AREA[numlocations], AREA[conditionsearch]; sort takes the index-only counts such as NumLocations too), and logs each correction

• Geographic proximity search and nearest-site re-ranking, with no geocoding dependency

• Excludes the "unknown" enrollment sentinel (99999999) from searches and counts by default; includeUnknownEnrollment brings it back

Agent-friendly output:

• Provenance — search, count, and eligibility tools echo searchCriteria; clinicaltrials_get_study_results names canonicalNctId when an alias ID resolves to another study

• Graceful partial failure — clinicaltrials_get_study_results returns per-study fetchErrors / studiesWithoutResults for IDs that fail on their own instead of failing the whole batch

• Typed errors — each tool returns reason codes (study_not_found, blank_value, …), and bounded lists carry a next*Offset only when more remains

• Response shaping — search and eligibility return a compact index by default instead of the ~70KB full record

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-mcp-server": {
      "type": "streamable-http",
      "url": "https://clinicaltrials.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with Docker:

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/clinicaltrialsgov-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.4 or higher (or Node.js v24+).

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 optional — the server works with defaults and no API keys.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

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

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, and security audit
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t clinicaltrialsgov-mcp-server .
docker run --rm -p 3010:3010 clinicaltrialsgov-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/clinicaltrialsgov-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

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 via the barrels in src/mcp-server/*/definitions/index.ts

• Validate raw API responses, normalize to domain types, and never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.