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

💻 使用示例

基礎用法

綜合使用示例可在 目錄中找到：

• 列出研究
• 獲取研究詳情

📚 詳細文檔

配置

使用環境變量配置服務器。對於本地開發，可以在項目根目錄的 .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 文件。