Clinicaltrialsgov MCP Server

🚀 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

从源代码安装

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建项目：

npm run build

💻 使用示例

基础用法

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

• 列出研究
• 获取研究详情

📚 详细文档

配置

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

项目结构

代码库在 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 提供了一套全面的临床试验研究工具，可通过模型上下文协议调用：

注意：所有工具都支持全面的错误处理，并返回结构化的 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 数据库交互的专业工具：

📄 许可证

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