clinicaltrialsgov-mcp-server

公共托管服务器： https://clinicaltrials.caseyjhand.com/mcp

概览

用于搜索、发现、分析和匹配临床试验的七个工具：

Related MCP server: Healthcare MCP Server

工具

clinicaltrials_search_studies

具备完整 ClinicalTrials.gov 查询能力的主要搜索工具。

• 全文和特定字段查询（疾病状况、干预措施、申办方、地点、标题、结果）

• 带有类型化枚举值的状态和阶段过滤器

• 按坐标和距离进行的地理邻近度过滤

• 支持复杂查询的高级 AREA[] Essie 表达式

• 字段选择以减小负载大小（完整记录每条约 70KB）

• 使用游标令牌进行分页，支持按任意字段排序

clinicaltrials_get_study_results

获取已完成研究的已发布结果数据。

• 包含统计数据、不良事件、参与者流程、基线特征的结果指标

• 节级过滤（仅请求您需要的数据）

• 可选的摘要模式将完整结果（约 200KB）压缩为基本元数据（每项研究约 5KB）

• 每次调用可批量处理多个 NCT ID，并提供部分成功报告

• 对无结果的研究和获取错误进行单独跟踪

clinicaltrials_find_eligible

将患者资料与符合条件的招募中试验进行匹配。

• 以年龄、性别、疾病状况和地点作为患者人口统计学信息

• 使用人口统计学过滤器（年龄范围、性别、健康志愿者）构建优化的 API 查询

• 返回包含资格和地点字段的研究，供调用者评估

• 当没有匹配的研究时提供可操作的提示（扩大疾病状况范围、调整过滤器）

特性

基于 @cyanheads/mcp-ts-core 构建：

• 带有 Zod 模式和格式化函数的声明式工具/资源/提示词定义

• 统一的错误处理 — 处理程序抛出异常，框架捕获并分类

• 双重传输：同一代码库支持 stdio 和 Streamable HTTP

• 可插拔的身份验证（none、jwt、oauth），用于 HTTP 传输

• 结构化日志记录，支持可选的 OpenTelemetry 追踪

ClinicalTrials.gov 特定功能：

• 针对 ClinicalTrials.gov REST API v2 的类型安全客户端

• 公共 API — 无需身份验证或 API 密钥

• 带有指数退避（3 次尝试）和速率限制（约 1 次请求/秒）的重试机制

• HTML 错误检测和结构化错误工厂

入门指南

公共托管实例

公共实例位于 https://clinicaltrials.caseyjhand.com/mcp — 无需安装。通过 Streamable HTTP 将任何 MCP 客户端指向它：

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "streamable-http",
      "url": "https://clinicaltrials.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

添加到您的 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["clinicaltrialsgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

或者对于 Streamable HTTP：

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

先决条件

• Bun v1.2.0 或更高版本（或 Node.js >= 22.0.0）

安装

1. 克隆仓库：

   git clone https://github.com/cyanheads/clinicaltrialsgov-mcp-server.git

2. 进入目录：

   cd clinicaltrialsgov-mcp-server

3. 安装依赖：

   bun install

配置

所有配置均为可选 — 服务器在默认设置下无需 API 密钥即可工作。

运行服务器

本地开发

• 构建并运行生产版本：

  bun run build
  bun run start:http   # or start:stdio

• 在开发模式下运行（带监听）：

  bun run dev:http     # or dev:stdio

• 运行检查和测试：

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite

Docker

docker build -t clinicaltrialsgov-mcp-server .
docker run -p 3010:3010 clinicaltrialsgov-mcp-server

项目结构

开发指南

请参阅 CLAUDE.md 获取开发准则和架构规则。简而言之：

• 处理程序抛出异常，框架捕获 — 工具逻辑中不要使用 try/catch

• 使用 ctx.log 进行请求范围的日志记录，不要使用 console 调用

• 在 index.ts 索引文件中注册新工具和资源

贡献

欢迎提交问题和拉取请求。提交前请运行检查：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。