金大哥 - clinicaltrialsgov-mcp-server MCP 详情

article

README

🚀 ClinicalTrials.gov MCP Server

ClinicalTrials.gov MCP Server 为AI智能体提供了直接访问官方ClinicalTrials.gov数据库的能力，能让大语言模型（LLMs）和AI智能体以编程方式搜索、检索和分析临床研究数据。该服务器基于 cyanheads/mcp-ts-template 构建，采用模块化架构，具备强大的错误处理、日志记录和安全功能。

🚀 快速开始

ClinicalTrials.gov MCP Server 充当了一座桥梁，使理解模型上下文协议（MCP）的应用程序（MCP客户端），如高级AI助手（LLMs）、IDE扩展或自定义研究工具，能够直接且高效地与官方ClinicalTrials.gov数据库进行交互。借助该服务器，你的工具可以自动化临床研究工作流程、获取研究见解、将临床试验数据集成到AI驱动的研究中，以及支持监管和合规工作流程。

✨ 主要特性

核心实用工具

日志记录：结构化、可配置的日志记录（文件轮转、标准输出JSON、MCP通知），支持敏感数据编辑。
错误处理：集中式错误处理，标准化错误类型（McpError），并自动记录日志。
配置管理：使用 dotenv 加载环境变量，并通过 Zod 进行全面验证。
输入验证/清理：使用 zod 进行模式验证和自定义清理逻辑。
请求上下文：通过 AsyncLocalStorage 使用唯一请求 ID 跟踪和关联操作。
类型安全：由 TypeScript 和 Zod 模式强制执行强类型。
HTTP 传输：使用 Hono 的高性能 HTTP 服务器，支持会话管理和身份验证。
身份验证：强大的身份验证层，支持 JWT 和 OAuth 2.1，并进行细粒度的范围控制。
部署：多阶段 Dockerfile，用于创建支持原生依赖的小型安全生产镜像。

ClinicalTrials.gov 集成

官方 API 集成：全面访问 ClinicalTrials.gov v2 API 端点，并自动解析 JSON。
高级搜索功能：支持复杂查询构建，可根据研究状态、地理位置、条件、干预措施和赞助商进行过滤。
完整研究元数据：检索完整的试验数据，包括方案、入选标准、研究设计、结果、赞助商和联系信息。
灵活的字段选择：选择特定的数据字段进行检索，以提高 API 使用效率并减少响应大小。
分页支持：使用 pageSize 和 pageToken 参数处理大型结果集。
数据清理：自动清理和简化 API 响应中的冗余信息，便于使用。
速率限制合规：内置请求限流功能，以遵守 ClinicalTrials.gov API 指南。

📦 安装指南

前提条件

Node.js (>=18.0.0)
npm（随 Node.js 一起安装）

MCP 客户端设置

将以下内容添加到你的 MCP 客户端配置文件（例如 cline_mcp_settings.json）中。此配置使用 npx 运行服务器，如果包尚未安装，将自动进行安装：

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "command": "npx",
      "args": ["clinicaltrialsgov-mcp-server"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

手动运行（非通过 MCP 客户端，用于开发或测试）

通过 npm 安装

npm install clinicaltrialsgov-mcp-server

从源代码安装

克隆仓库：

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

安装依赖：

npm install

构建项目：

npm run build

💻 使用示例

基础用法

综合使用示例可在 examples/ 目录中找到：

📚 详细文档

配置

使用环境变量配置服务器。对于本地开发，可以在项目根目录的 .env 文件中设置这些变量，也可以直接在环境中设置。否则，你可以在 MCP 客户端配置中设置它们，如下所示：

| 属性 | 详情 | |------|------| | MCP_TRANSPORT_TYPE | 传输机制：stdio 或 http，默认值为 stdio | | MCP_HTTP_PORT | HTTP 服务器的端口（如果 MCP_TRANSPORT_TYPE=http），默认值为 3010 | | MCP_HTTP_HOST | HTTP 服务器的主机地址（如果 MCP_TRANSPORT_TYPE=http），默认值为 127.0.0.1 | | MCP_ALLOWED_ORIGINS | CORS 允许的源的逗号分隔列表（如果 MCP_TRANSPORT_TYPE=http），默认无 | | MCP_LOG_LEVEL | 日志记录级别（debug, info, notice, warning, error, crit, alert, emerg），默认值为 debug | | MCP_AUTH_MODE | HTTP 身份验证模式：jwt 或 oauth，默认值为 jwt | | MCP_AUTH_SECRET_KEY | jwt 身份验证所需的至少 32 个字符的密钥，默认无 | | CLINICALTRIALS_DATA_PATH | 缓存 ClinicalTrials.gov API 数据的目录，默认值为 data/ | | LOGS_DIR | 日志文件存储目录，默认值为 logs/ | | NODE_ENV | 运行时环境（development, production），默认值为 development |

项目结构

代码库在 src/ 目录下遵循模块化结构：

src/
├── index.ts              # 入口点：初始化并启动服务器
├── config/               # 配置加载（环境变量、包信息）
│   └── index.ts
├── mcp-server/           # 核心 MCP 服务器逻辑和功能注册
│   ├── server.ts         # 服务器设置，功能注册
│   ├── transports/       # 传输处理（stdio, http）
│   └── tools/            # MCP 工具实现（每个工具一个子目录）
├── services/             # 外部服务集成
│   └── clinical-trials-gov/ # ClinicalTrials.gov API 客户端和类型
├── types-global/         # 共享 TypeScript 类型定义
└── utils/                # 通用实用函数（日志记录器、错误处理程序等）

如需详细的文件树，请运行 npm run tree 或查看 docs/tree.md。

工具

ClinicalTrials.gov MCP Server 提供了一套全面的临床试验研究工具，可通过模型上下文协议调用：

| 工具名称 | 描述 | 关键参数 | | ---- | ---- | ---- | | clinicaltrials_list_studies | 使用查询、过滤器和分页搜索临床试验研究 | query?, filter?, fields?, sort?, pageSize?, pageToken?, countTotal? | | clinicaltrials_get_study | 通过 NCT ID 获取一个或多个研究的详细信息 | nctIds, summaryOnly?, markupFormat?, fields? | | clinicaltrials_analyze_trends | 对一组研究进行统计分析 | analysisType, query?, filter? |

注意：所有工具都支持全面的错误处理，并返回结构化的 JSON 响应。

开发

# 构建项目（将 TS 编译为 JS 并生成可执行文件）
npm run build

# 使用 MCP 检查器工具在本地测试服务器（stdio 传输）
npm run inspector

# 使用 MCP 检查器工具在本地测试服务器（http 传输）
npm run inspector:http

# 清理构建产物
npm run clean

# 生成用于文档的文件树表示
npm run tree

# 清理构建产物，然后重建项目
npm run rebuild

# 使用 Prettier 格式化代码
npm run format

# 使用 stdio 启动服务器（默认）
npm start
# 或显式指定：
npm run start:stdio

# 使用 HTTP 传输启动服务器
npm run start:http

🔧 技术细节

核心功能：ClinicalTrials.gov 工具

该服务器为你的 AI 提供了与 ClinicalTrials.gov 数据库交互的专业工具：

| 工具名称 | 描述 | 关键特性 | | ---- | ---- | ---- | | clinicaltrials_list_studies | 使用查询词和过滤器的组合搜索临床试验研究。（参见示例） | - query：按条件、术语、位置、标题、干预措施、结果、赞助商或 ID 进行搜索。
- filter：按 NCT ID、研究状态、地理距离或高级 Essie 表达式细化结果。
- pagination：使用 pageSize 和 pageToken 控制结果集。
- fields：指定返回哪些数据字段以提高效率。 | | clinicaltrials_get_study | 通过 NCT ID 获取一个或多个临床试验研究的详细信息。（参见示例） | - nctIds：使用唯一标识符（例如 "NCT03934567"）获取最多 5 项研究。
- summaryOnly：返回压缩摘要而不是完整数据。
- fields：选择要检索的特定字段。
- markupFormat：选择 markdown 或 legacy 作为格式化内容。 | | clinicaltrials_analyze_trends | 对一组研究进行统计分析，按状态、国家、赞助商或阶段汇总数据。 | - analysisType：选择汇总方法（countByStatus, countByCountry 等）。
- query & filter：使用与 list_studies 相同强大的搜索参数定义分析数据集。
- 每次请求最多分析 5000 项研究。 |

📄 许可证

本项目采用 Apache License 2.0 许可协议，详情请参阅 LICENSE 文件。

基于 Model Context Protocol 构建

clinicaltrialsgov-mcp-server