--- ## Tools Seven tools for working with ClinicalTrials.gov data: | Tool Name | Description | | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | | `clinicaltrials_search_studies` | Searches for clinical studies using query terms, filters, pagination, and sorting. Includes geographic and enum-based filtering. | | `clinicaltrials_get_study` | Fetches one or more clinical studies by their NCT IDs, returning either full data or concise summaries. | | `clinicaltrials_get_study_results` | Fetches trial results data for completed studies — outcomes, adverse events, participant flow, and baseline characteristics. | | `clinicaltrials_get_field_values` | Discovers valid enum values for any API field with study counts, enabling informed query construction. | | `clinicaltrials_analyze_trends` | Performs statistical analysis on up to 5000 studies by status, country, sponsor, phase, year, month, study type, or intervention type. | | `clinicaltrials_compare_studies` | Side-by-side comparison of 2-5 clinical studies across eligibility, design, interventions, outcomes, and sponsors. | | `clinicaltrials_find_eligible_studies` | Matches patient profiles to eligible clinical trials, filtering by age, sex, conditions, and location. Returns studies sorted by proximity. | ### `clinicaltrials_search_studies` Search for clinical trials using free-text queries and filters. - Full-text search plus specialized condition, intervention, and sponsor queries targeting specific API indexes - Typed enum filters for study status and phase (single value or array) - Geographic proximity filtering by coordinates and distance - Advanced filtering with ClinicalTrials.gov's AREA[] syntax - Pagination (up to 200 per page), sorting, and field selection [View detailed examples](./examples/clinicaltrials_search_studies.md) --- ### `clinicaltrials_get_study` Fetch one or more clinical trials by NCT ID, with full data or concise summaries. - Batch fetch up to 5 studies at once - Full data includes protocol sections, results, adverse events, outcome measures, eligibility, and locations - Partial success reporting when some studies in a batch fail [View detailed examples](./examples/clinicaltrials_get_study.md) --- ### `clinicaltrials_analyze_trends` Aggregate statistics across up to 5,000 studies by status, country, sponsor, phase, year, month, study type, or intervention type. - Combine multiple analysis types in a single request - Filter to focus on specific subsets - Returns counts and top categories (percentages omitted for phase breakdowns, where multi-phase studies make the denominator ambiguous) [View detailed examples](./examples/clinicaltrials_analyze_trends.md) --- ### `clinicaltrials_compare_studies` Compare 2-5 studies side-by-side across eligibility, design, interventions, outcomes, sponsors, and locations. - Configurable comparison fields — compare everything or focus on specific aspects - Handles partial failures if some studies can't be fetched [View detailed examples](./examples/clinicaltrials-compare-studies.md) --- ### `clinicaltrials_find_eligible_studies` Match a patient profile (age, sex, conditions, location) to eligible clinical trials. - Hard filters on age, sex, healthy volunteer status, and country — ineligible studies are excluded entirely - Condition token overlap used as a false-positive gate (studies with zero relevance to the patient's conditions are excluded) - Results sorted by location proximity: city match → state match → country-only, then by number of nearby sites - Returns a summary of why each study is a potential match [View detailed examples](./examples/clinicaltrials-find-eligible-studies.md) --- ### `clinicaltrials_get_study_results` Fetch results data (outcomes, adverse events, participant flow, baseline characteristics) for completed studies. - Section-level filtering — request only the sections you need - Batch up to 5 studies per request - Reports which studies lack results or failed to fetch - Includes statistical analyses (p-values, methods) with outcome data --- ### `clinicaltrials_get_field_values` Look up valid enum values for any ClinicalTrials.gov API field, with study counts per value. - Sorted by frequency - Useful for exploring OverallStatus, Phase, InterventionType, StudyType, and other fields before constructing filters ## Features Built on [`mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template): - Declarative tool definitions — single file per tool, framework handles registration and validation - Unified `McpError` error handling across all tools - Pluggable auth (`none`, `jwt`, `oauth`) - Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2` - Structured logging (Pino) with optional OpenTelemetry tracing - Typed DI container with `Token` phantom branding - Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase ClinicalTrials.gov-specific: - Type-safe client for the ClinicalTrials.gov v2 API - Tools for search, filtering, statistical aggregation, and patient matching - Automatic cleaning and simplification of API responses for agent consumption ## 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": { "type": "streamable-http", "url": "https://clinicaltrials.caseyjhand.com/mcp" } } } ``` ### Self-Hosted / Local Add the following to your MCP Client configuration file (e.g., `cline_mcp_settings.json`). ```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: ```bash MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3017 ``` ### Prerequisites - [Bun v1.2.0](https://bun.sh/) or higher. ### Installation 1. **Clone the repository:** ```sh git clone https://github.com/cyanheads/clinicaltrialsgov-mcp-server.git ``` 2. **Navigate into the directory:** ```sh cd clinicaltrialsgov-mcp-server ``` 3. **Install dependencies:** ```sh bun install ``` ## 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`, `cloudflare-r2`, `cloudflare-d1`. | `in-memory` | | `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` | | `MCP_LOG_LEVEL` | The minimum level for logging (RFC 5424: `debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). | `info` | | `MCP_AUTH_SECRET_KEY` | ** ---