cyanheads/clinicaltrialsgov-mcp-server

🛠️ Tools Overview

This server provides five powerful tools for accessing and analyzing clinical trial data from ClinicalTrials.gov:

clinicaltrials_search_studies

Search and discover clinical trials using free-text queries and advanced filters.

Key Features:

• Free-text search across all study fields (conditions, interventions, sponsors, titles)
• Advanced filtering with ClinicalTrials.gov's official filter syntax
• Pagination support for large result sets (up to 200 studies per page)
• Sorting by enrollment count, update date, or other fields
• Returns concise summaries with NCT IDs, titles, and recruitment status

Example Use Cases:

• "Find all Phase 3 diabetes studies currently recruiting"
• "Show me cancer immunotherapy trials in the United States"
• "List studies by pharmaceutical companies sorted by size"

📖

clinicaltrials_get_study

Retrieve detailed information for specific clinical trials by their NCT ID.

Key Features:

• Fetch single or multiple studies (up to 5 at once)
• Choice between full data (complete protocol, results, documents) or concise summaries
• Full study data includes: protocol sections, results, adverse events, outcome measures, eligibility criteria, locations, and more
• Automatic error handling for invalid or non-existent NCT IDs
• Partial success reporting when fetching multiple studies

Example Use Cases:

• "Get the full details for study NCT03372603"
• "Show me a summary of these three studies: NCT12345678, NCT87654321, NCT11223344"
• "What were the results and adverse events for NCT04280783?"

📖

clinicaltrials_analyze_trends

Perform statistical analysis across thousands of clinical trials.

Key Features:

• Aggregate up to 5,000 studies per analysis
• Multiple analysis types: status distribution, geographic spread, sponsor types, trial phases
• Combine multiple analysis types in a single request
• Advanced filtering to focus analysis on specific subsets
• Returns counts, percentages, and top categories

Example Use Cases:

• "What's the status breakdown of all COVID-19 vaccine Phase 3 trials?"
• "Which countries have the most Alzheimer's research studies?"
• "Show me the phase distribution and sponsor types for cancer immunotherapy trials"

📖

clinicaltrials_compare_studies

Compare and contrast multiple studies to identify key similarities and differences.

Key Features:

• Side-by-side comparison of 2-5 studies by NCT ID
• Extracts and contrasts eligibility, design, interventions, outcomes, sponsors, and more
• Generates a summary of commonalities and differences
• Handles partial failures gracefully if some studies cannot be fetched
• Highly configurable to focus on specific fields of interest

Example Use Cases:

• "Compare the study design and eligibility criteria for NCT04516746 and NCT04516759"
• "What are the main differences in interventions and outcomes between these three leading Alzheimer's trials?"
• "Show me a side-by-side of sponsor and location data for these competitor studies"

📖

clinicaltrials_find_eligible_studies

Find relevant clinical trials based on a patient's specific medical profile and demographics.

Key Features:

• Matches patients using age, sex, and a list of medical conditions
• Filters studies by location (country, state, city) to find nearby trials
• Ranks results by a relevance score based on how well the patient matches the study's criteria
• Provides a clear summary of why a patient is a potential match for a study

Example Use Cases:

• "Find recruiting migraine studies in Canada for a 35-year-old female"
• "Are there any local clinical trials for a 68-year-old male with Type 2 Diabetes and Hypertension?"
• "Search for healthy volunteer studies for a 25-year-old in California"

📖

✨ Features

This server is built on the mcp-ts-template and inherits its rich feature set:

• Declarative Tools: Define agent capabilities in single, self-contained files. The framework handles registration, validation, and execution.
• Robust Error Handling: A unified McpError system ensures consistent, structured error responses.
• Pluggable Authentication: Secure your server with zero-fuss support for none, jwt, or oauth modes.
• Abstracted Storage: Swap storage backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) without changing business logic.
• Full-Stack Observability: Deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
• Dependency Injection: Built with tsyringe for a clean, decoupled, and testable architecture.
• Edge-Ready: Write code once and run it seamlessly on your local machine or at the edge on Cloudflare Workers.

Plus, specialized features for ClinicalTrials.gov:

• Official API Integration: Type-safe, comprehensive access to the ClinicalTrials.gov v2 API.
• Advanced Search & Analysis: Tools for complex queries, filtering, and statistical aggregation of trial data.
• Optimized Data Handling: Automatic cleaning and simplification of API responses for efficient agent consumption.

🚀 Getting Started

MCP Client Settings/Configuration

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

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

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

🛠️ Core Capabilities: ClinicalTrials.gov Tools

This server equips AI agents with specialized tools to interact with the ClinicalTrials.gov database.

⚙️ 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

🧑‍💻 Agent Development Guide

For strict rules when using this server with an AI agent, refer to the .clinerules file in this repository. Key principles include:

• Logic Throws, Handlers Catch: Never use try/catch in your tool logic. Throw an McpError instead.
• Pass the Context: Always pass the RequestContext object through your call stack for logging and tracing.
• Use the Barrel Exports: Register new tools and resources only in the index.ts barrel files within their respective definitions directories.

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