Registry / llm-agents / clinicaltrialsgov-mcp-server

clinicaltrialsgov-mcp-server

JSON →
library2.3.4jsnpmunverified

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.

npm install clinicaltrialsgov-mcp-server
INSTALL
IMPORT
SIG · CLINICALTRIALSGOV-
C
clinicaltrialsgov-mcp-server
llm-agentsjavascriptv2.3.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ClinicalTrialsGovMcpServer
import { ClinicalTrialsGovMcpServer } from 'clinicaltrialsgov-mcp-server';
const ClinicalTrialsGovMcpServer = require('clinicaltrialsgov-mcp-server');
The package is ESM-first and primarily consumed via `import`. CommonJS `require` is generally not supported for main exports without specific configuration.
McpServerConfig
import type { McpServerConfig } from 'clinicaltrialsgov-mcp-server';
import { McpServerConfig } from 'clinicaltrialsgov-mcp-server'; // Incorrect for type-only import
When importing interfaces or types, use `import type` for clarity and to ensure they are stripped from the JavaScript output, preventing accidental runtime imports.
start
import { start } from 'clinicaltrialsgov-mcp-server/http'; // For HTTP server specific startup
import { start } from 'clinicaltrialsgov-mcp-server';
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.

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.

import { ClinicalTrialsGovMcpServer } from 'clinicaltrialsgov-mcp-server'; import { ConsoleLogger } from '@cyanheads/logger'; // Assumed dependency for logging import dotenv from 'dotenv'; dotenv.config(); async function main() { const port = parseInt(process.env.PORT ?? '3000', 10); const clinicalTrialsApiKey = process.env.CLINICALTRIALS_API_KEY ?? ''; if (!clinicalTrialsApiKey) { console.warn("Warning: CLINICALTRIALS_API_KEY is not set. The server might not be able to access ClinicalTrials.gov API without proper authentication."); } try { // Initialize the MCP Server with configuration const server = new ClinicalTrialsGovMcpServer({ port, logger: new ConsoleLogger(), // Inject a logger implementation clinicalTrialsGovApiKey: clinicalTrialsApiKey, // Other configurations like 'storageBackend' or 'authMechanism' might be needed // depending on specific deployment and security requirements. }); server.on('ready', () => { console.log(`ClinicalTrials.gov MCP Server listening on http://localhost:${port}`); console.log('Available tools include search, study details retrieval, and patient matching.'); console.log('Refer to the documentation for specific API endpoints (e.g., /search, /study/:nctId).'); }); server.on('error', (error) => { console.error('MCP Server encountered an error:', error); process.exit(1); }); // Start the server instance await server.start(); console.log('MCP Server started successfully.'); } catch (error) { console.error('Failed to initialize or start the MCP Server:', error); process.exit(1); } } main();
clinicaltrialsgov-mcp-server --version
Debug
Known issues
breakingThe 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.
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`.
affects: <2.x
gotchaAccessing 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.
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.
affects: >=1.0.0
breakingOlder 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.
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.
affects: <2.0.0
gotchaThe 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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not supported
Attempting to use CommonJS `require()` syntax to import the `clinicaltrialsgov-mcp-server` package, which is an ESM-first module.
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`.
Error: listen EADDRINUSE: address already in use :::3000
Another process is already using the specified port (e.g., 3000).
fix
Change the `PORT` environment variable or the `port` configuration option to an available port, or terminate the process currently using that port.
TypeError: Cannot read properties of undefined (reading 'search')
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.
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.
Upgrade
Version history
2.3.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
16
OpenAI (training)
1
Resources