ClinicalTrials.gov MCP Server

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not supported

  cause 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

  cause 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')

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

Warnings

• breaking 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.
  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`.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install clinicaltrialsgov-mcp-server npm
• yarn add clinicaltrialsgov-mcp-server yarn
• pnpm add clinicaltrialsgov-mcp-server pnpm

Imports

• ClinicalTrialsGovMcpServer
  wrong:

  const ClinicalTrialsGovMcpServer = require('clinicaltrialsgov-mcp-server');

  correct:

  import { ClinicalTrialsGovMcpServer } from '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
  wrong:

  import { McpServerConfig } from 'clinicaltrialsgov-mcp-server'; // Incorrect for type-only import

  correct:

  import type { McpServerConfig } from 'clinicaltrialsgov-mcp-server';

  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
  wrong:

  import { start } from 'clinicaltrialsgov-mcp-server';

  correct:

  import { start } from 'clinicaltrialsgov-mcp-server/http'; // For HTTP server specific startup

  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.

Quickstart

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();