Clinicaltrialsgov Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv2.11.1Updated Nov 4, 2026

Search ClinicalTrials.gov: find studies, retrieve results, match patients to candidate trials.

VerifiedStreamable HTTPWeb executableKnowledge & MemoryData & Analytics

Overview

AI-generated overview

Read-only access to ClinicalTrials.gov: search 600K+ studies, fetch records and posted results, and match patients to candidate trials.

What you can do
  • Search studies with full-text, condition, intervention, sponsor, location and geographic filters, sorting and pagination
  • Fetch a single study's full protocol record by NCT ID, with optional caps on locations, outcomes and references
  • Get fast total counts for a query, and discover valid field names and field values with per-value counts
  • Retrieve posted results for completed studies: outcomes, adverse events, participant flow and baseline characteristics
  • Match a patient profile (age, sex, conditions, location) to candidate recruiting trials, without checking inclusion/exclusion criteria
  • Read a single study as a JSON resource and use a guided prompt for trial landscape analysis
When to use it
Useful when you need to research a condition's trial landscape, look up a specific trial by NCT ID, read posted results, or shortlist recruiting trials for a patient profile. It is read-only and needs no account, so it is low-risk to add for medical, research or literature work.
Requirements
Either the public hosted Streamable HTTP endpoint, or a local process via npx/bunx (Node.js v24+ or Bun v1.4.0+) or Docker. No API key or account is needed; all configuration variables are optional. Network access to the ClinicalTrials.gov API is required.
Before you install
All tools are read-only against a public registry, but patient-matching inputs (age, sex, conditions, location) are sent to ClinicalTrials.gov. Eligibility matching does not check inclusion/exclusion criteria, so results are candidates only, not medical advice. Optional failure-payload logging (LOG_TOOL_FAILURE_PAYLOADS) can record tool arguments, and secrets inside free-form values are not redacted.

Installation

In SourceWeft

  1. Open Clinicaltrialsgov Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fclinicaltrialsgov-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

README

clinicaltrialsgov-mcp-server

Search ClinicalTrials.gov trials, retrieve study details and results, and match patients to candidate trials via MCP. STDIO or Streamable HTTP.

7 Tools • 1 Resource • 1 Prompt • 1 Skill

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

ToolDescription
clinicaltrials_search_studiesSearch studies with full-text and field-specific queries, status/phase/geographic filters, pagination, sorting, and field selection
clinicaltrials_get_study_recordFetch a single study by NCT ID — full protocol record with optional location/outcome/reference caps
clinicaltrials_get_study_countFast total study count for a query, without fetching data
clinicaltrials_get_field_valuesDiscover valid values for API fields, with per-value study counts
clinicaltrials_get_field_definitionsResolve valid field names — keyword search, path drill-down, or top-level overview
clinicaltrials_get_study_resultsFetch posted results — outcomes, adverse events, participant flow, baseline — for completed studies
clinicaltrials_find_eligibleMatch patient demographics and conditions to candidate recruiting trials, without checking inclusion/exclusion criteria

Resources

ResourceDescription
clinicaltrials://{nctId}Fetch a single clinical study by NCT ID as JSON, with capped lists and results replaced by counts

Prompts

PromptDescription
analyze_trial_landscapeGuides a data-driven clinical trial landscape analysis using the count and search tools

Skills

SkillDescription
clinicaltrialsgov-guideGates and query syntax the tool descriptions don't carry: study versus site recruiting status, overlapping phase counts, RANGE and MISSING with partial dates and open-ended age limits, the status vocabulary, and reading posted results

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.

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 1–1000 (default 10; 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 fields
  • Returns a compact per-study index by default (nctId, briefTitle, overallStatus, phases, enrollmentCount, hasResults, …); fields (PascalCase leaves) 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

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
  • filtersApplied reports upstream totals when a cap trims a list; resultsSection is replaced by resultsSummary counts. Typed errors: study_not_found, rate_limited

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

clinicaltrials_get_field_values tool

  • One or more PascalCase fields (e.g. OverallStatus, Phase) — 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

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, and clinicaltrials_get_field_values
  • Typed errors: blank_value, mode_mismatch, mode_requires, path_not_found, rate_limited

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 instead of a whole-batch failure, and canonicalNctId when an alias ID resolves to another study. Typed errors: blank_value, offset_not_applicable, rate_limited

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 (up to 1000; 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, query_parse_error, request_too_long, rate_limited

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

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
  • Auto-corrects field names passed to fields/sort (case, whitespace, legacy aliases like RecruitmentStatus → OverallStatus) 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 pieces 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 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:

json
{  "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.

json
{  "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):

json
{  "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:

json
{  "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:

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

Prerequisites

Installation

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/clinicaltrialsgov-mcp-server.git
  1. Navigate into the directory:
sh
cd clinicaltrialsgov-mcp-server
  1. Install dependencies:
sh
bun install

Configuration

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

VariableDescriptionDefault
CT_API_BASE_URLClinicalTrials.gov API base URL.https://clinicaltrials.gov/api/v2
CT_REQUEST_TIMEOUT_MSPer-request timeout in milliseconds; a positive integer.30000
CT_MAX_PAGE_SIZEMost studies one clinicaltrials_search_studies page returns; an integer ≥ 1, values above 1000 clamp to 1000.200
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto.stateless
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
OTEL_ENABLEDEnable OpenTelemetry tracing.false
OTEL_EXPORTER_OTLP_ENDPOINTOTLP base URL for traces and metrics.—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTLP endpoint for log export.—
LOG_TOOL_FAILURE_PAYLOADSLog each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.false

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

Running the server

Local development

  • Build and run:

    sh
    # One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdio

  • Run checks and tests:

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

Docker

sh
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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools/resources/prompts/skills and inits the ClinicalTrials.gov service.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts).
src/mcp-server/resourcesResource definitions (*.resource.ts).
src/mcp-server/promptsPrompt definitions (*.prompt.ts).
src/services/clinical-trialsClinicalTrials.gov REST API v2 client — retry, rate limiting, field search, types.
skills/The published clinicaltrialsgov-guide skill for agents calling the tools.
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 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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

Source: README.md at commit 3c61c43

Tools

7

clinicaltrials_search_studies

Clinicaltrials Search Studies

Search for clinical trial studies from ClinicalTrials.gov. Supports full-text and field-specific queries, status/phase/geographic filters, pagination, sorting, and field selection. Returns a compact per-study index by default; pass the fields parameter to get specific leaves at full fidelity — full study records are ~70KB each.

ParameterssortqueryfieldsnctIdspageSizegeoFilterpageTokencountTotaltitleQueryphaseFilteroutcomeQuerysponsorQuery+6 more

clinicaltrials_get_study_record

Clinicaltrials Get Study Record

Fetch a single clinical trial study by NCT ID from ClinicalTrials.gov. Returns the full study record including protocol details, eligibility criteria, outcomes, arms, interventions, contacts, and locations. Optional locationLimit / outcomeLimit / referenceLimit / nearLocation parameters trim locations, outcomes, and references — original totals are preserved in `filtersApplied` only when a cap actually trims the set.

ParametersnctIdrequirednearLocationoutcomeLimitlocationLimitreferenceLimit

clinicaltrials_get_study_count

Clinicaltrials Get Study Count

Get total clinical trial study count from ClinicalTrials.gov matching a query, without fetching study data. Fast and lightweight. Use for quick statistics or to build breakdowns by calling multiple times with different filters (e.g., count by phase, count by status, count recruiting vs completed for a condition).

ParametersquerytitleQueryphaseFilteroutcomeQuerysponsorQuerystatusFilterlocationQueryadvancedFilterconditionQueryinterventionQueryincludeUnknownEnrollment

clinicaltrials_get_field_values

Clinicaltrials Get Field Values

Discover valid values for ClinicalTrials.gov fields with study counts per value. Use to explore available filter options before building a search — e.g., valid OverallStatus, Phase, InterventionType, StudyType, or LeadSponsorClass values.

Parametersfieldsrequired

clinicaltrials_get_field_definitions

Clinicaltrials Get Field Definitions

Resolve valid field names from the ClinicalTrials.gov data model — the canonical PascalCase identifiers (OverallStatus, EnrollmentCount, LeadSponsorName) accepted by the `fields`, `advancedFilter`, and `sort` parameters of other tools, and as input to clinicaltrials_get_field_values. Select a mode: `"search"` — keyword search returning ranked matches (pass `query`, e.g. "enrollment", "sponsor", "adverse events"); `"drill"` — drill into a specific section by dot-notation path (pass `path`, e.g. "protocolSection.designModule"); `"overview"` — top-level summary of all sections (no additional args).

ParametersmoderequiredpathlimitqueryincludeIndexedOnly

clinicaltrials_get_study_results

Clinicaltrials Get Study Results

Fetch clinical trial results data from ClinicalTrials.gov for completed studies — outcome measures with statistics, adverse events, participant flow, baseline characteristics, and results metadata (limitations & caveats, certain-agreement disclosure restrictions, results point of contact). Only available for studies where hasResults is true. Use clinicaltrials_search_studies first to find studies with results. Each call fetches up to 20 distinct NCT IDs and returns any further IDs in deferredNctIds for a follow-up call. A results-rich record can exceed 500KB per study in full mode — bound it with summary=true, narrower sections, or the outcomeLimit / adverseEventLimit caps; outcomeLimit / outcomeOffset also page summarized outcomes. A bounded list is resumable: outcomeOffset / seriousEventOffset / otherEventOffset start the next window, and each study's filtersApplied reports what was trimmed and the next offset for every list left short. A previous (alias) NCT ID resolves to its canonical study, named in canonicalNctId.

ParametersnctIdsrequiredsummarysectionsoutcomeLimitoutcomeOffsetotherEventOffsetadverseEventLimitseriousEventOffset

clinicaltrials_find_eligible

Clinicaltrials Find Eligible

Find candidate clinical trials for a patient profile. Provide age, sex, conditions, and location to get studies with their demographic limits, contact information, and recruiting locations. Candidates are matched on age, sex, location, recruitment status, and ClinicalTrials.gov's fuzzy condition search only — inclusion/exclusion criteria are not checked, and a candidate can exclude the requested condition, so review each one's criteria with clinicaltrials_get_study_record before treating it as a match. Results are re-ranked so studies whose own condition matches a requested condition surface above tangential matches from ClinicalTrials.gov's fuzzy condition search. Each candidate returns only the sites matching the requested location (capped by locationLimit), not the study's full registered site list — a large trial can register hundreds of sites worldwide. When none of a candidate's matched sites is recruiting, one recruiting site is added so an enrollable site is never hidden behind a closer closed one: the one nearest the matched sites by their published coordinates, in the requested country whenever a site there recruits, carrying distanceMi, or the first in match order when coordinates are missing. Fetch a study's complete record with clinicaltrials_get_study_record.

ParametersagerequiredsexrequiredageUnitlocationrequiredconditionsrequiredmaxResultslocationLimitrecruitingOnlyhealthyVolunteer

Version history

9
  1. v2.11.1LatestNov 4, 2026
  2. v2.11.0Nov 3, 2026
  3. v2.10.2Oct 26, 2026
  4. v2.10.1Oct 23, 2026
  5. v2.10.0Oct 14, 2026
  6. v2.9.11Oct 5, 2026
  7. v2.9.10Sep 23, 2026
  8. v2.9.8Sep 18, 2026
  9. v2.9.7Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts