ClinicalTrialsGov Mcp Server

What is ClinicalTrialsGov Mcp Server about?

ClinicalTrialsGov Mcp Server offers a production‑grade, multi‑tenant Model Context Protocol (MCP) server that exposes three high‑level tools for interacting with the ClinicalTrials.gov database: searching studies, fetching detailed study records, and performing aggregate trend analyses. The server is built for performance, scalability, and edge deployment (e.g., Cloudflare Workers), and includes robust error handling, authentication options, and pluggable storage back‑ends.

How to use ClinicalTrialsGov Mcp Server?

1. Clone and install the repository.

   git clone https://github.com/cyanheads/clinicaltrialsgov-mcp-server.git
   cd clinicaltrialsgov-mcp-server
   bun install   # or use your preferred package manager
   

2. Configure required environment variables (port, auth mode, storage provider, etc.) in a .env file. See the src/config/index.ts table for all options.
3. Run the server locally or as a Cloudflare Worker.
   • Local HTTP server: bun start:http
   • STDIO mode: bun start:stdio
   • Worker bundle: bun build:worker then deploy with Wrangler.
4. Add the server to an MCP client configuration, for example:

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

5. Invoke tools from an LLM agent using the defined tool names (clinicaltrials_search_studies, clinicaltrials_get_study, clinicaltrials_analyze_trends).

Key features of ClinicalTrialsGov Mcp Server

• Three declarative tools covering search, detailed retrieval, and statistical aggregation.
• Advanced search syntax with free‑text, filters, pagination, and sorting.
• Batch fetching of up to 5 studies per request, with optional full or summary payloads.
• Trend analysis on up to 5,000 studies, supporting status, geographic, sponsor, and phase breakdowns.
• Edge‑ready architecture – runs unchanged on local machines or Cloudflare Workers.
• Pluggable authentication (none, jwt, oauth).
• Multiple storage back‑ends (in‑memory, filesystem, Supabase, Cloudflare KV/R2).
• Observability via structured Pino logs and optional OpenTelemetry tracing.
• Dependency injection with tsyringe for clean, testable code.

Use cases of ClinicalTrialsGov Mcp Server

• Clinical decision support: An AI assistant can quickly locate recruiting trials matching a patient’s condition and location.
• Research meta‑analysis: Generate aggregated statistics on trial phases, sponsor types, or geographic distribution for a therapeutic area.
• Regulatory monitoring: Track status changes (e.g., recruiting → completed) for a set of NCT IDs.
• Pharma competitive intelligence: Identify the most active sponsors or countries in a therapeutic field.
• Educational tools: Provide concise study summaries for students learning about clinical research design.

FAQ from the ClinicalTrialsGov Mcp Server

Q: Do I need an API key for ClinicalTrials.gov? A: No. The official ClinicalTrials.gov v2 API is open and does not require authentication.

Q: How many studies can I retrieve in a single call? A: The clinicaltrials_get_study tool accepts up to 5 NCT IDs per request; the search tool paginates up to 200 results per page.

Q: What is the maximum size for trend analysis? A: Up to 5,000 studies can be aggregated in a single clinicaltrials_analyze_trends request.

Q: Can I run this server on the edge? A: Yes. Build the Cloudflare Worker bundle with bun build:worker and deploy via Wrangler.

Q: How is authentication handled? A: The server supports three modes—none (default), jwt (requires MCP_AUTH_SECRET_KEY), and oauth (requires OAUTH_ISSUER_URL). Choose the mode via the MCP_AUTH_MODE environment variable.

Q: What storage options are available? A: Configure STORAGE_PROVIDER_TYPE to one of in-memory, filesystem, supabase, cloudflare-kv, or r2.

Q: How do I enable OpenTelemetry? A: Set OTEL_ENABLED=true; the server will automatically emit traces and metrics.

---

🛠️ Tools Overview

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

Tool Name	Description
clinicaltrials_search_studies	Searches for clinical studies using a combination of query terms and filters. Supports pagination, sorting, and geographic filtering.
clinicaltrials_get_study	Fetches one or more clinical studies by their NCT IDs. Returns either complete study data or concise summaries for each.
clinicaltrials_analyze_trends	Performs statistical analysis on studies, aggregating data by status, country, sponsor, or phase. Handles up to 5000 studies per analysis.

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 →

✨ 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"],
      "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:

Variable	Description	Default
MCP_TRANSPORT_TYPE	The transport to use: stdio or http.	http
MCP_HTTP_PORT	The port for the HTTP server.	3010
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

2. Run locally with Wrangler:

bun deploy:dev

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