Clinical Trial Gov MCP

🏥 ClinicalTrials.gov MCP Server

A semantic intelligence layer for clinical trial data

Transform how AI agents interact with 400,000+ clinical trials

Built with ❤️ by Suyash Ekhande for the clinical trials research community

Features • Quick Start • Tools • Examples • Architecture

______________________________________________________________________

https://github.com/user-attachments/assets/87839f47-84fd-44ac-b1e5-4438cea40f92

🎯 这是什么？

这是一个 模型上下文协议（MCP） 为AI代理提供智能语义访问的服务器 ClinicalTrials.gov --世界上最大的临床研究数据库。

与简单的API包装器不同，此服务器提供 10个高级语义工具 了解临床研究工作流程：

______________________________________________________________________

✨ 特性

🔍 智能搜索

• 自然语言查询支持
• 自动翻译为Essie语法
• 20+滤波器参数
• 基于邻近度的位置搜索

🎯 患者匹配

• 资格评分（0-100）
• 年龄/性别/状况匹配
• 详细说明
• 下一步指导

📊 计算指标

• 试验成熟度评估
• 入学速度分析
• 完成可能性
• 市场饱和度得分

🏢 竞争情报

• 类似的试验发现
• 赞助商渠道分析
• 治疗区域测绘
• 合作网络

📈 分析

• 招生能力分析
• 地理分布
• 疾病景观趋势
• 字段值统计

📤 导出和格式化

• JSON、CSV、Markdown输出
• 分组策略
• 汇总统计
• 批处理

______________________________________________________________________

🚀 快速开始

先决条件

• Python 3.11+
• pip或任何Python包管理器

安装

选项1:pip（建议用于开发）

# Clone the repository
git clone https://github.com/yourusername/clinicaltrials-mcp.git
cd clinicaltrials-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

选项2:Docker

# Clone the repository
git clone https://github.com/yourusername/clinicaltrials-mcp.git
cd clinicaltrials-mcp

# Build the image
docker build -t clinicaltrials-mcp .

# Run the container
docker run -p 8000:8000 clinicaltrials-mcp

运行服务器

# Start the MCP server (HTTP transport on port 8000)
python server.py

╭──────────────────────────────╮
│     FastMCP 2.14.1           │
│                              │
│  🖥  Server: clinicaltrials  │
│  📦 Transport: HTTP          │
│  🔗 URL: http://0.0.0.0:8000 │
╰──────────────────────────────╯

与任何代理IDE/CLI连接

{
  "mcpServers": {
    "clinicaltrials": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

______________________________________________________________________

🛠 工具

核心工具

分析工具

情报工具

______________________________________________________________________

💬 例子

患者试验匹配

*“我是加利福尼亚州一名55岁的男性2型糖尿病患者。我可以参加哪些临床试验？”*

result = await match_patient_to_trials(
    age=55,
    gender="MALE",
    primary_condition="Type 2 Diabetes",
    location_state="California",
    must_be_recruiting=True
)
# Returns: Matched trials with eligibility scores and explanations

竞争情报

*“查找所有使用检查点抑制剂的3期NSCLC试验，并分析竞争格局”*

# Search for trials
trials = await search_clinical_trials(
    query="NSCLC AND checkpoint inhibitor",
    trial_phase=["PHASE3"],
    enrollment_status=["RECRUITING"]
)

# Analyze similar trials for a reference
similar = await find_similar_trials(
    reference_nct_id="NCT04000165",
    similarity_dimensions=["CONDITION", "INTERVENTION", "PHASE"]
)

赞助商分析

*“分析辉瑞的肿瘤学管道——他们的活跃试验和治疗重点领域是什么？”*

result = await analyze_sponsor_network(
    sponsor_name="Pfizer",
    analyze_therapeutic_areas=True,
    analyze_stage_distribution=True,
    analyze_collaboration_patterns=True
)
# Returns: Portfolio breakdown, phase distribution, top conditions, collaborators

市场分析

*“美国黑色素瘤试验的注册情况如何？”*

result = await get_enrollment_intelligence(
    condition="melanoma",
    location_country="United States",
    include_capacity_analysis=True,
    include_competitor_summary=True
)
# Returns: Market saturation, enrollment targets, top sponsors, recommendations

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Clients                               │
│              (Claude Desktop, AI Agents, etc.)                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Streamable HTTP (port 8000)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FastMCP Server                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    10 Semantic Tools                      │   │
│  │  search | analyze | match | metadata | similar | outcomes │   │
│  │  enrollment | sponsor | export | statistics               │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                   │
│  ┌─────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
│  │   Essie     │  │   Pagination    │  │    Metrics      │     │
│  │ Translator  │  │    Handler      │  │   Calculator    │     │
│  └─────────────┘  └─────────────────┘  └─────────────────┘     │
│                              │                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Async HTTP Client (aiohttp)                  │   │
│  │         TTL Caching | Retry Logic | Error Handling        │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ HTTPS
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                ClinicalTrials.gov API v2                         │
│                    400,000+ Studies                              │
└─────────────────────────────────────────────────────────────────┘

项目结构

clinicaltrials-gov-mcp/
├── server.py              # FastMCP server with 10 tools
├── config.py              # API settings, cache TTLs, field lists
├── core/
│   ├── api_client.py      # Async HTTP client with caching & retry
│   ├── models.py          # Pydantic schemas (28 enums, 15 models)
│   ├── pagination.py      # Token-based pagination handler
│   └── essie_translator.py # Natural language → Essie query syntax
├── tools/
│   ├── search.py          # Trial search with NL support
│   ├── analyze.py         # Trial analysis & similarity
│   ├── patient_match.py   # Patient eligibility matching
│   ├── metadata.py        # API schema introspection
│   ├── enrollment.py      # Enrollment intelligence
│   ├── sponsor.py         # Sponsor network analysis
│   ├── export.py          # Multi-format export
│   └── statistics.py      # Aggregate analytics
└── utils/
    ├── metrics.py         # Computed metrics (maturity, pace, etc.)
    └── formatting.py      # Output formatting (Markdown, CSV)

______________________________________________________________________

🔧 技术细节

关键设计决策

Essie查询语法

服务器自动翻译自然语言查询：

Input:  "lung cancer AND pembrolizumab in phase 3"
Output: AREA[Condition]"lung cancer" AND AREA[InterventionName]pembrolizumab AND AREA[Phase]PHASE3

Input:  "recruiting diabetes trials in California"
Output: AREA[Condition]diabetes AND AREA[OverallStatus]RECRUITING AND AREA[LocationState]"California"

计算指标

______________________________________________________________________

🧪 测试

# Run the test suite
python test_tools.py

这将针对实时API测试所有10个工具：

1️⃣  search_clinical_trials     ✅ SUCCESS
2️⃣  analyze_trial_details      ✅ SUCCESS
3️⃣  match_patient_to_trials    ✅ SUCCESS
4️⃣  get_trial_metadata_schema  ✅ SUCCESS
5️⃣  find_similar_trials        ✅ SUCCESS
6️⃣  analyze_trial_outcomes     ✅ SUCCESS
7️⃣  get_enrollment_intelligence ✅ SUCCESS
8️⃣  analyze_sponsor_network    ✅ SUCCESS
9️⃣  export_and_format_trials   ✅ SUCCESS
🔟 query_trial_statistics      ✅ SUCCESS

______________________________________________________________________

📚 api参考

此服务器与 ClinicalTrials.gov REST API v2.

使用的端点

• GET /studies --搜索和筛选研究
• GET /studies/{nctId} --检索单个研究详细信息
• GET /studies/metadata --数据模型模式
• GET /studies/enums --枚举值
• GET /studies/search-areas --可搜索字段
• GET /stats/* --汇总统计数据
• GET /version -API版本

______________________________________________________________________

🤝 贡献

欢迎投稿！请随时提交拉取请求。

1. 克隆该仓库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

______________________________________________________________________

致谢

• ClinicalTrials.gov 用于提供公共API
• FastMCP 优秀的MCP框架
• 模型上下文协议 对于规范

______________________________________________________________________

Built with ❤️ by Suyash Ekhande for the clinical trials research community