---

🛠️ Tools Overview

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

Tool Name	Description
clinicaltrials_search_studies	Searches for clinical studies using query terms, filters, pagination, and sorting. Now includes geographic filtering.
clinicaltrials_get_study	Fetches one or more clinical studies by their NCT IDs, returning either full data or concise summaries.
clinicaltrials_analyze_trends	Performs statistical analysis on up to 5000 studies, with new time-series analysis by year and month.
clinicaltrials_compare_studies	Performs a detailed side-by-side comparison of 2-5 clinical studies, highlighting commonalities and differences.
clinicaltrials_find_eligible_studies	Matches patient profiles to eligible clinical trials, filtering by age, sex, conditions, and location.

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"

📖 View detailed examples →

---

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

📖 View detailed examples →

---

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"

📖 View detailed examples →

---

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"

📖 View detailed examples →

---

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"

📖 View detailed examples →

✨ 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": {
      "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=3015

Prerequisites

• Bun v1.2.0 or higher.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/clinicaltrialsgov-mcp-server.git

1. Navigate into the directory:

cd clinicaltrialsgov-mcp-server

1. 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:

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, r2.	in-memory
OTEL_ENABLED	Set to true to enable OpenTelemetry.	false
LOG_LEVEL	The minimum level for logging (debug, info, warn, error).	info
MCP_AUTH_SECRET_KEY	Required for jwt auth. A 32+ character secret key.	(none)
OAUTH_ISSUER_URL	Required for oauth auth. URL of the OIDC provider.	(none)

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

1. Run locally with Wrangler:

bun deploy:dev

1. Deploy to Cloudflare:

   bun deploy:prod

📂 Project Structure

Directory	Purpose & Contents
src/mcp-server/tools	Your tool definitions (*.tool.ts). This is where you add new capabilities.
src/mcp-server/resources	Your resource definitions (*.resource.ts). This is where you add data sources.
src/mcp-server/transports	Implementations for HTTP and STDIO transports, including auth middleware.
src/storage	StorageService abstraction and all storage provider implementations.
src/services	Integrations with external services (ClinicalTrials.gov, LLMs, Speech).
src/container	Dependency injection container registrations and tokens.
src/utils	Core utilities for logging, error handling, performance, and security.
src/config	Environment variable parsing and validation with Zod.
tests/	Unit and integration tests, mirroring the src/ directory 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 LICENSE file for details.