{"id":16790,"library":"clinicaltrialsgov-mcp-server","title":"ClinicalTrials.gov MCP Server","description":"The `clinicaltrialsgov-mcp-server` package offers a robust Model-Context-Protocol (MCP) server solution for interacting with the ClinicalTrials.gov v2 API. Its core functionalities include comprehensive search capabilities for clinical trials, detailed retrieval of study information and results, and advanced patient-to-trial matching based on specified eligibility criteria. The package is currently stable at version 2.3.4, with a release cadence likely driven by API updates or feature enhancements. As a TypeScript-first server, it provides strong type safety and is designed to serve as a backend component, particularly useful for AI agents or LLMs that require structured, real-time access to clinical trial data. Key differentiators include its specialized focus on the ClinicalTrials.gov ecosystem and its MCP adherence, abstracting away much of the API complexity for developers building patient matching and research applications, offering a higher-level interface than direct API interaction. The server can run locally via HTTP or stdio, and is deployable to platforms like Cloudflare Workers.","status":"active","version":"2.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/cyanheads/clinicaltrialsgov-mcp-server","tags":["javascript","mcp","mcp-server","model-context-protocol","ai-agent","llm","llm-agent","typescript","clinical-trials"],"install":[{"cmd":"npm install clinicaltrialsgov-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add clinicaltrialsgov-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add clinicaltrialsgov-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-first and primarily consumed via `import`. CommonJS `require` is generally not supported for main exports without specific configuration.","wrong":"const ClinicalTrialsGovMcpServer = require('clinicaltrialsgov-mcp-server');","symbol":"ClinicalTrialsGovMcpServer","correct":"import { ClinicalTrialsGovMcpServer } from 'clinicaltrialsgov-mcp-server';"},{"note":"When importing interfaces or types, use `import type` for clarity and to ensure they are stripped from the JavaScript output, preventing accidental runtime imports.","wrong":"import { McpServerConfig } from 'clinicaltrialsgov-mcp-server'; // Incorrect for type-only import","symbol":"McpServerConfig","correct":"import type { McpServerConfig } from 'clinicaltrialsgov-mcp-server';"},{"note":"Depending on the deployment target (HTTP or stdio), specific entry points like `clinicaltrialsgov-mcp-server/http` or `clinicaltrialsgov-mcp-server/stdio` might expose direct `start` functions or specific configurations.","wrong":"import { start } from 'clinicaltrialsgov-mcp-server';","symbol":"start","correct":"import { start } from 'clinicaltrialsgov-mcp-server/http'; // For HTTP server specific startup"}],"quickstart":{"code":"import { ClinicalTrialsGovMcpServer } from 'clinicaltrialsgov-mcp-server';\nimport { ConsoleLogger } from '@cyanheads/logger'; // Assumed dependency for logging\nimport dotenv from 'dotenv';\n\ndotenv.config();\n\nasync function main() {\n  const port = parseInt(process.env.PORT ?? '3000', 10);\n  const clinicalTrialsApiKey = process.env.CLINICALTRIALS_API_KEY ?? '';\n\n  if (!clinicalTrialsApiKey) {\n    console.warn(\"Warning: CLINICALTRIALS_API_KEY is not set. The server might not be able to access ClinicalTrials.gov API without proper authentication.\");\n  }\n\n  try {\n    // Initialize the MCP Server with configuration\n    const server = new ClinicalTrialsGovMcpServer({\n      port,\n      logger: new ConsoleLogger(), // Inject a logger implementation\n      clinicalTrialsGovApiKey: clinicalTrialsApiKey,\n      // Other configurations like 'storageBackend' or 'authMechanism' might be needed\n      // depending on specific deployment and security requirements.\n    });\n\n    server.on('ready', () => {\n      console.log(`ClinicalTrials.gov MCP Server listening on http://localhost:${port}`);\n      console.log('Available tools include search, study details retrieval, and patient matching.');\n      console.log('Refer to the documentation for specific API endpoints (e.g., /search, /study/:nctId).');\n    });\n\n    server.on('error', (error) => {\n      console.error('MCP Server encountered an error:', error);\n      process.exit(1);\n    });\n\n    // Start the server instance\n    await server.start();\n    console.log('MCP Server started successfully.');\n\n  } catch (error) {\n    console.error('Failed to initialize or start the MCP Server:', error);\n    process.exit(1);\n  }\n}\n\nmain();\n","lang":"typescript","description":"This quickstart demonstrates how to initialize and start the `clinicaltrialsgov-mcp-server` locally, handling port configuration and API key loading from environment variables. It also shows basic error and ready event handling."},"warnings":[{"fix":"Ensure your environment uses Node.js `>=22.0.0` or Bun `>=1.2.0`. Update your runtime or use a version manager like `nvm` or `fnm`.","message":"The package enforces specific Node.js and Bun runtime versions. Using incompatible versions (Node < 22.0.0 or Bun < 1.2.0) will result in runtime errors or build failures.","severity":"breaking","affected_versions":"<2.x"},{"fix":"Set the `CLINICALTRIALS_API_KEY` environment variable with your valid API key before starting the server, or pass it explicitly in the server configuration. Refer to ClinicalTrials.gov developer documentation for key acquisition.","message":"Accessing the ClinicalTrials.gov API requires an API key, which must be configured in the server. Running the server without a valid key will likely result in failed API calls and limited functionality.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the `CHANGELOG.md` or GitHub release notes for specific breaking changes between major versions. Update your configuration and tool definitions to align with the latest MCP specification and server API.","message":"Older versions of this package or its underlying `mcp-ts-template` might have breaking changes related to the Model Context Protocol specification. Ensure compatibility if upgrading from a significantly older major version.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Review the package's documentation or the `tools` directory in the source code to understand the available MCP tools and their usage. Clients (e.g., LLMs) need to be configured to correctly call these tools.","message":"The server exposes its functionality through various 'tools' (e.g., search, retrieve study details, patient matching). Proper client-side integration requires understanding these tool definitions and their expected inputs/outputs, especially for LLM agents.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Convert your consuming module to ES Modules by using `import` statements and ensuring your `package.json` has `\"type\": \"module\"` or files end with `.mjs`.","cause":"Attempting to use CommonJS `require()` syntax to import the `clinicaltrialsgov-mcp-server` package, which is an ESM-first module.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not supported"},{"fix":"Change the `PORT` environment variable or the `port` configuration option to an available port, or terminate the process currently using that port.","cause":"Another process is already using the specified port (e.g., 3000).","error":"Error: listen EADDRINUSE: address already in use :::3000"},{"fix":"Ensure the `CLINICALTRIALS_API_KEY` environment variable is correctly set and is a valid API key. Verify that server initialization is complete before attempting to use its tools or endpoints.","cause":"This error often occurs when the `clinicalTrialsGovApiKey` is missing or invalid, leading to the underlying ClinicalTrials.gov client failing to initialize properly, or when a tool is called before the server is fully ready.","error":"TypeError: Cannot read properties of undefined (reading 'search')"}],"ecosystem":"npm","meta_description":null}