chictr-mcp-server

v2.0.2

Published

a month ago

MCP Server for querying ChiCTR clinical trials

Downloads

465

0High
0Medium
0Low

xiaoyibao_2025

mcp clinical-trials chictr medical-research

ChiCTR MCP Server

ChiCTR MCP Server 是一个基于 Model Context Protocol (MCP) 的临床试验查询服务，专门用于查询中国临床试验注册中心 (ChiCTR) 的临床试验信息。

当前版本: v2.0.2

🔔 版本更新

v2.0.2 (2026-04-09)

✅ 修复详情空对象缓存命中问题（自动失效并重查）
✅ 进一步提升详情查询的有效内容获取稳定性

v2.0.1 (2026-04-09)

✅ 修复 Cherry Studio 场景下 ./cache 路径导致的启动失败（ENOENT）
✅ 默认缓存路径调整为 ~/.chictr/cache/chictr_cache.db
✅ 增加 /tmp/chictr/cache/chictr_cache.db 兜底路径

v2.0.0 (2026-04-09)

✅ 新增请求编排层（限速/重试/熔断）
✅ 新增 Session 池化与生命周期回收
✅ 新增挑战状态机与恢复工具（get_access_state / prepare_verification_session / resume_after_verification）
✅ 新增双层缓存（L1 内存 + L2 SQLite）与 get_cache_stats_v2

v1.2.1 (2025-01-17)

✅ 更新 README，添加多维度搜索示例
✅ 添加版本升级指南
✅ 提供 Cherrystudio 缓存清除方案

v1.2.0 (2025-01-17)

✅ 新增按注册号搜索（registration_number 参数）
✅ 新增按年份搜索（year 参数，默认当前年份）
✅ 所有搜索参数改为可选
✅ 修复详情查询 400 错误（使用正确的 project_id）

v1.1.0 (2025-01-17)

✅ 修复分页功能，支持多页结果获取
✅ 支持代理配置（HTTP_PROXY/HTTPS_PROXY）
✅ 增加验证码检测与友好错误提示

📍 快速导航

🐛 已知问题

频繁请求可能触发滑动验证码，建议使用代理或增加请求间隔
headless 模式下无法手动处理验证码

🎯 支持的 MCP 服务类型

stdio: 标准输入输出通信（默认）
http: HTTP REST API 服务（计划中）
sse: Server-Sent Events 实时通信服务（计划中）

🌟 功能特点

MCP 协议兼容: 完全支持 Model Context Protocol 标准
多维度搜索: 支持按标题关键词、注册号、年份搜索
详细信息: 提供临床试验的完整详细信息
高性能: 内置智能缓存机制，提升查询速度
反爬虫处理: 使用浏览器自动化技术应对网站防护机制

🚀 快速开始

MCP JSON 最简配置（推荐）

将以下内容放入你的 MCP 客户端配置文件：

{
  "mcpServers": {
    "chictr": {
      "command": "npx",
      "args": ["-y", "chictr-mcp-server@latest"]
    }
  }
}

如果你已全局安装（npm i -g chictr-mcp-server），可用更短配置：

{
  "mcpServers": {
    "chictr": {
      "command": "chictr-mcp-server"
    }
  }
}

安装依赖

npm install

编译项目

npm run build

启动服务器

STDIO 模式（默认）

npm start
# 或
node dist/index.js

# 带参数启动（未来版本支持）
# node dist/index.js --transport=http --port=3000

📋 可用工具

search_trials

搜索临床试验，支持按标题关键词、注册号、年份进行搜索

// 按关键词搜索
{
  "name": "search_trials",
  "arguments": {
    "keyword": "KRAS",
    "max_results": 20
  }
}

// 按注册号搜索
{
  "name": "search_trials",
  "arguments": {
    "registration_number": "ChiCTR2500111173"
  }
}

// 按年份搜索
{
  "name": "search_trials",
  "arguments": {
    "year": 2024,
    "max_results": 20
  }
}

// 组合搜索
{
  "name": "search_trials",
  "arguments": {
    "keyword": "KRAS",
    "year": 2024,
    "max_results": 10
  }
}

参数说明：

keyword (可选): 注册题目关键词
registration_number (可选): 临床试验注册号
year (可选): 注册年份，默认当前年份
max_results (可选): 最大返回结果数，默认20

get_trial_detail

查询试验详情

{
  "name": "get_trial_detail",
  "arguments": {
    "registration_number": "ChiCTR2500108082"
  }
}

get_cache_stats

获取缓存统计信息

{
  "name": "get_cache_stats",
  "arguments": {}
}

clear_cache

清除所有缓存

{
  "name": "clear_cache",
  "arguments": {}
}

get_cache_stats_v2

获取双层缓存统计（L1 + L2 SQLite）

{
  "name": "get_cache_stats_v2",
  "arguments": {}
}

get_runtime_metrics

获取运行时编排指标（限速/重试/挑战计数/会话统计）

{
  "name": "get_runtime_metrics",
  "arguments": {}
}

get_access_state

获取访问状态机信息（NORMAL/SUSPECTED/CHALLENGED/COOLDOWN/RECOVERY）

{
  "name": "get_access_state",
  "arguments": {}
}

prepare_verification_session

创建人工验证会话

{
  "name": "prepare_verification_session",
  "arguments": {
    "target_url": "https://www.chictr.org.cn/searchproj.html",
    "timeout_ms": 300000
  }
}

resume_after_verification

人工验证完成后恢复访问状态

{
  "name": "resume_after_verification",
  "arguments": {
    "verification_id": "verify_xxx"
  }
}

🛠️ CLI 命令行工具

安装 CLI

# 全局安装
npm install -g chictr-mcp-server

# 或者直接使用 npx（推荐）
npx -y chictr-mcp-server

使用 CLI

# 启动 STDIO 服务
chictr-mcp-server

# 或使用 npx
npx -y chictr-mcp-server

# 带参数启动（未来版本支持）
# chictr-mcp-server --transport=http --port=3000
# chictr-mcp-server --transport=sse --port=3000
# chictr-mcp-server --help

🛠️ 技术栈

TypeScript: 类型安全的 JavaScript 超集
Playwright: 浏览器自动化工具
Cheerio: 服务器端 jQuery 实现
Node-Cache: 高性能缓存库
SQLite (better-sqlite3): 持久化二级缓存
MCP SDK: Model Context Protocol 官方 SDK

🔧 高级配置

代理设置（可选）

如果您需要使用代理访问 ChiCTR，可以通过环境变量配置：

# 设置 HTTP 代理
export HTTP_PROXY=http://your-proxy-server:port

# 或者 HTTPS 代理
export HTTPS_PROXY=http://your-proxy-server:port

# 然后启动服务
npx -y chictr-mcp-server

MCP 客户端中使用代理

{
  "mcpServers": {
    "chictr": {
      "command": "npx",
      "args": ["-y", "chictr-mcp-server"],
      "env": {
        "HTTP_PROXY": "http://your-proxy-server:port"
      }
    }
  }
}

注意：

代理配置是可选的，大多数情况下不需要
如果频繁触发验证码，建议使用代理或更换 IP
本项目不提供代理服务，需要用户自行准备

📡 MCP 配置说明

MCP 客户端配置

使用 npx（推荐，最简配置）

{
  "mcpServers": {
    "chictr": {
      "command": "npx",
      "args": ["-y", "chictr-mcp-server@latest"]
    }
  }
}

使用本地安装

npm install -g chictr-mcp-server

{
  "mcpServers": {
    "chictr": {
      "command": "chictr-mcp-server"
    }
  }
}

HTTP 模式配置（计划中）

{
  "mcpServers": {
    "chictr": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

SSE 模式配置（计划中）

{
  "mcpServers": {
    "chictr": {
      "type": "sse",
      "url": "http://localhost:3000/mcp"
    }
  }
}

🚀 MCP 测试

要测试 MCP 服务，您可以使用以下命令：

npx @modelcontextprotocol/inspector npx -y chictr-mcp-server

需要提前安装 @modelcontextprotocol/inspector

npm install -g @modelcontextprotocol/inspector

📊 性能优化

智能缓存: 搜索结果缓存 5 分钟，详情数据缓存 10 分钟
浏览器自动化: 使用 Playwright 模拟真实浏览器行为
反爬虫处理: 内置 User-Agent 和延迟机制

🧪 使用示例

查询 KRAS G12D 相关试验

# 搜索最近 6 个月的 KRAS G12D 相关试验
{
  "name": "search_trials",
  "arguments": {
    "keyword": "KRAS G12D",
    "months": 6,
    "max_results": 10
  }
}

查询特定试验详情

# 查询注册号为 ChiCTR2500108082 的试验详情
{
  "name": "get_trial_detail",
  "arguments": {
    "registration_number": "ChiCTR2500108082"
  }
}

📈 查询结果示例

搜索结果

{
  "results": [
    {
      "registration_number": "ChiCTR2500108082",
      "title": "谷氨酰胺联合奥沙利铂、卡培他滨（XELOX）和贝伐珠单抗一线治疗KRAS G12D基因突变型晚期结直肠癌的单臂Ⅱ期探索性研究",
      "study_type": "干预性研究",
      "registration_date": "2025/08/25",
      "institution": "浙江大学医学院附属第二医院"
    }
  ]
}

🔧 配置说明

TypeScript 配置

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

缓存配置

搜索结果缓存: 5 分钟 (300 秒)
详情数据缓存: 10 分钟 (600 秒)

🤝 集成方式

ChiCTR MCP Server 当前支持 STDIO 通信方式，可以轻松集成到任何支持 MCP 协议的应用中：

STDIO 模式（默认）

通过标准输入输出与客户端通信，适用于大多数 MCP 客户端。

HTTP 模式（计划中）

通过 HTTP REST API 与客户端通信，支持跨网络访问。

端点: http://localhost:3000/mcp
方法: POST
Content-Type: application/json

SSE 模式（计划中）

通过 Server-Sent Events 与客户端通信，支持实时推送。

端点: http://localhost:3000/mcp
事件类型: message

📄 许可证

MIT License

📞 支持

如有问题，请提交 GitHub Issue。

🙏 致谢

本项目使用中国临床试验注册中心 (ChiCTR) 的公开数据，感谢 ChiCTR 为医学研究做出的贡献。特别感谢小胰宝和小x宝社区的❤️贡献与付出，用爱心与人工智能为癌症/罕见病患者及其家庭提供支持！

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ChiCTR MCP Server

🔔 版本更新

v2.0.2 (2026-04-09)

v2.0.1 (2026-04-09)

v2.0.0 (2026-04-09)

v1.2.1 (2025-01-17)

v1.2.0 (2025-01-17)

v1.1.0 (2025-01-17)

📍 快速导航

🐛 已知问题

🎯 支持的 MCP 服务类型

🌟 功能特点

🚀 快速开始

MCP JSON 最简配置（推荐）

安装依赖

编译项目

启动服务器

STDIO 模式（默认）

📋 可用工具

search_trials

get_trial_detail

get_cache_stats

clear_cache

get_cache_stats_v2

get_runtime_metrics

get_access_state

prepare_verification_session

resume_after_verification

🛠️ CLI 命令行工具

安装 CLI

使用 CLI

🛠️ 技术栈

🔧 高级配置

代理设置（可选）

MCP 客户端中使用代理

📡 MCP 配置说明

MCP 客户端配置

使用 npx（推荐，最简配置）

使用本地安装

HTTP 模式配置（计划中）

SSE 模式配置（计划中）

🚀 MCP 测试

📊 性能优化

🧪 使用示例

查询 KRAS G12D 相关试验

查询特定试验详情

📈 查询结果示例

搜索结果

🔧 配置说明

TypeScript 配置

缓存配置

🤝 集成方式

STDIO 模式（默认）

HTTP 模式（计划中）

SSE 模式（计划中）

📄 许可证

📞 支持

🙏 致谢