PluginBench
MCP Server
Active
Apache-2.0

io.github.cyanheads/clinicaltrialsgov-mcp-server MCP Server

io.github.cyanheads/clinicaltrialsgov-mcp-server

Search ClinicalTrials.gov, retrieve study details and results, and match patients to eligible trials.

RepositoryRegistry
How to choose

What this kind of tool is for

  • Let your agent search the web or a document set and cite what it found.
  • Pull structured facts out of pages instead of copy-pasting by hand.
  • Track changes on a topic over days without re-reading everything.

How to compare servers like this

Source coverage:
Check which engines, sites, or document types the tool can actually reach.
Citation behavior:
Prefer tools that return links you can open, not just summarized claims.
Terms of service:
Some sources forbid automated access; make sure the tool stays inside them.
Maintenance signal:
Scrapers break silently when pages change; recent commits are the best proxy.

This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.

What is the io.github.cyanheads/clinicaltrialsgov-mcp-server MCP server?

The clinicaltrialsgov-mcp-server is an MCP server that provides access to ClinicalTrials.gov data through seven tools for searching, analyzing, and matching clinical trials. It enables AI agents to search studies with filters, retrieve full study records and results, discover field values, and match patient demographics to eligible recruiting trials.

This server connects Claude and other MCP clients to ClinicalTrials.gov's REST API, letting you search for clinical trials by condition, intervention, location, and status; retrieve detailed study protocols, eligibility criteria, and posted results; and match patient profiles to eligible recruiting trials. It's useful for researchers, healthcare providers, and patients exploring trial options without needing direct API access.

How to install io.github.cyanheads/clinicaltrialsgov-mcp-server

Copy-paste configuration for popular MCP clients.

transport: stdio
Config generated by PluginBench — verify against the source before use.
Environment / auth
  • CT_API_BASE_URL

    ClinicalTrials.gov API base URL.

  • CT_REQUEST_TIMEOUT_MS

    Per-request timeout in milliseconds.

  • CT_MAX_PAGE_SIZE

    Maximum page size cap.

  • MCP_LOG_LEVEL

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

  • MCP_HTTP_HOST

    The hostname for the HTTP server.

  • MCP_HTTP_PORT

    The port to run the HTTP server on.

  • MCP_HTTP_ENDPOINT_PATH

    The endpoint path for the MCP server.

  • MCP_AUTH_MODE

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

~/Library/Application Support/Claude/claude_desktop_config.json
JSON config
{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "command": "bun",
      "args": [
        "-y",
        "clinicaltrialsgov-mcp-server",
        "run",
        "start:stdio"
      ],
      "env": {
        "CT_API_BASE_URL": "<YOUR_CT_API_BASE_URL>",
        "CT_REQUEST_TIMEOUT_MS": "<YOUR_CT_REQUEST_TIMEOUT_MS>",
        "CT_MAX_PAGE_SIZE": "<YOUR_CT_MAX_PAGE_SIZE>",
        "MCP_LOG_LEVEL": "<YOUR_MCP_LOG_LEVEL>",
        "MCP_HTTP_HOST": "<YOUR_MCP_HTTP_HOST>",
        "MCP_HTTP_PORT": "<YOUR_MCP_HTTP_PORT>",
        "MCP_HTTP_ENDPOINT_PATH": "<YOUR_MCP_HTTP_ENDPOINT_PATH>",
        "MCP_AUTH_MODE": "<YOUR_MCP_AUTH_MODE>"
      }
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

  • clinicaltrials_search_studies — Search studies with full-text queries, filters, pagination, sorting, and field selection. Supports condition, intervention, sponsor, location, title, outcome queries, status and phase filters, and geographic proximity filtering.
  • clinicaltrials_get_study_record — Fetch a single study by NCT ID. Returns the full record including protocol, eligibility criteria, outcomes, arms, interventions, contacts, and locations.
  • clinicaltrials_get_study_count — Get total study count for a query without fetching data. Provides fast statistics and breakdowns by field values.
  • 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 with piece names, types, and nesting. Supports subtree navigation and keyword search.
  • clinicaltrials_get_study_results — Extract outcomes, adverse events, participant flow, and baseline characteristics from completed studies. Includes optional summary mode to reduce payload size.
  • clinicaltrials_find_eligible — Match patient demographics (age, sex, conditions, location) to eligible recruiting trials. Returns studies with eligibility criteria and recruiting locations.

Use cases

  • Search for clinical trials matching a patient's condition and location to identify enrollment opportunities
  • Retrieve detailed study protocols and eligibility criteria for a specific trial by NCT ID
  • Extract and analyze posted results data including outcomes and adverse events from completed studies
  • Discover what clinical trial phases, statuses, and study types are available in the database
  • Match a patient profile to recruiting trials that meet their demographic and medical criteria

io.github.cyanheads/clinicaltrialsgov-mcp-server MCP server FAQ

What is the clinicaltrialsgov-mcp-server?

It's an MCP server that provides AI agents access to ClinicalTrials.gov data through tools for searching trials, retrieving study details and results, and matching patients to eligible studies.

Do I need an API key or authentication?

No. The server uses ClinicalTrials.gov's public REST API v2, which requires no authentication or API keys.

How do I install it in Claude Desktop or Cursor?

You can install it via npm (npx clinicaltrialsgov-mcp-server), use the provided one-click install buttons in the GitHub repository, or point to the public hosted instance at https://clinicaltrials.caseyjhand.com/mcp.

Is there a public hosted version I can use without installing?

Yes. A public instance is available at https://clinicaltrials.caseyjhand.com/mcp. Configure it as a streamable-http server in your MCP client config.

What data can I retrieve about a clinical trial?

You can get study protocols, eligibility criteria, outcomes, adverse events, participant flow, baseline characteristics, interventions, arms, contacts, and recruiting locations.

Can I match a patient to eligible trials?

Yes. The clinicaltrials_find_eligible tool takes patient age, sex, conditions, and location, then returns recruiting trials with matching eligibility criteria and nearby recruiting sites.

README (reference)

Source of truth, from the repository.

<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">

npm Docker Version MCP SDK License TypeScript Bun

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

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

</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 NameDescription
clinicaltrials_search_studiesSearch studies with full-text queries, filters, pagination, sorting, and field selection.
clinicaltrials_get_study_recordFetch a single study by NCT ID. Returns the full record: protocol, eligibility, outcomes, arms, interventions, contacts, and locations.
clinicaltrials_get_study_countGet total study count for a query without fetching data. Fast statistics and breakdowns.
clinicaltrials_get_field_valuesDiscover valid values for API fields (status, phase, study type, etc.) with per-value counts.
clinicaltrials_get_field_definitionsBrowse the study data model field tree — piece names, types, nesting. Supports subtree navigation and keyword search.
clinicaltrials_get_study_resultsExtract outcomes, adverse events, participant flow, and baseline from completed studies. Optional summary mode reduces ~200KB payloads to ~5KB; outcomeLimit / adverseEventLimit cap full mode without leaving it.
clinicaltrials_find_eligibleMatch 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.
ResourceDescription
clinicaltrials://{nctId}Fetch a single clinical trial study by NCT ID. Protocol JSON with capped locations/outcomes/references and results replaced by counts; omissions reported with the tool that retrieves them.
PromptDescription
analyze_trial_landscapeAdaptable 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
  • Bounds each candidate to the sites matching the requested location (capped by locationLimit) rather than every site the study registers worldwide, adds the nearest recruiting site when none of the matched ones is open, and discloses what was omitted
  • 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:

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

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

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.

VariableDescriptionDefault
CT_API_BASE_URLClinicalTrials.gov API base URL.https://clinicaltrials.gov/api/v2
CT_REQUEST_TIMEOUT_MSPer-request timeout in milliseconds.30000
CT_MAX_PAGE_SIZEMaximum page size cap.200
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
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

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

DirectoryPurpose
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.

Related MCP servers

Read, write, and inspect the system clipboard on macOS, Linux (X11/Wayland), and Windows via MCP.

1
TypeScript
Apache-2.0
View repository →

Crypto market data via CoinGecko — prices, markets, history, trending, and deep coin metadata.

1
TypeScript
Apache-2.0
View repository →

Search, compare, and analyze U.S. college data — costs, earnings, programs, and outcomes.

1
TypeScript
View repository →

Access U.S. congressional data - bills, votes, members, committees - via MCP.

1
TypeScript
Apache-2.0
View repository →

Search US court opinions, federal dockets, judges, citations, and oral arguments via CourtListener.

2
TypeScript
View repository →

US consumer product recalls from the CPSC — hazards, remedies, and affected products.

1
TypeScript
Apache-2.0
View repository →