Skip to main content
Glama
clinical-mcp

clinical-mcp

by sarathi-aiml

clinical-mcp

一个用于临床工作流的 MCP 服务器:搜索和总结合成 FHIR R4 患者记录、从 PubMed 获取文献、对自由文本进行去标识化——全部通过 Claude(或任何 MCP 客户端)完成。

作为参考级 MCP 服务器构建:它实现了完整的规范面(工具、资源和提示——大多数公开服务器只做到工具),附带一套测试套件来验证线上协议,并支持通过 stdio 或带认证的可流式 HTTP 运行。

所有患者数据均为合成数据,由 Synthea 生成。本项目任何地方都不存在真实的 PHI。

Architecture

[Claude / MCP client]
        |  stdio  or  streamable-http (+ bearer auth)
        v
[clinical-mcp  (MCPServer)]
   |-- tools ------ search_patients, get_patient_summary, get_observations,
   |                search_pubmed, get_pubmed_abstract, deidentify_text
   |-- resources -- fhir://patients            (roster)
   |                fhir://patients/{id}       (full record, URI template)
   |-- prompts ---- clinical_summary, literature_review
   |
   +-- FhirStore ----------- in-memory index over Synthea FHIR R4 bundles
   +-- PubMedClient -------- NCBI E-utilities, rate-limited (3/s, 10/s w/ key)
   +-- deidentify() -------- HIPAA Safe Harbor regex redaction

Quick start

pip install clinical-mcp

Claude Desktop / Claude Code 配置(mcpServers 条目):

{
  "clinical": {
    "command": "clinical-mcp",
    "env": { "CLINICAL_MCP_DATA_DIR": "/path/to/fhir/bundles" }
  }
}

从源码运行:

git clone https://github.com/sarathi-aiml/clinical-mcp
cd clinical-mcp
pip install -e ".[dev]"
clinical-mcp                       # stdio, serves the bundled 10-patient sample
pytest                             # 33 tests, no network needed

然后向 Claude 提问,例如:

"查找 50 岁以上患有高血压的女性患者,总结第一位患者,并获取与她用药清单相关的三篇最新 PubMed 论文。"

Tools

工具

功能

search_patients

按姓名、性别、年龄范围或诊断条件筛选患者名单

get_patient_summary

人口统计学信息 + 疾病、用药、过敏、免疫接种

get_observations

实验室检查和生命体征,可按 FHIR 类别、名称和日期筛选

search_pubmed

通过 NCBI E-utilities 进行 PubMed 搜索(支持 [MeSH] 等字段标签)

get_pubmed_abstract

获取 PMID 的完整摘要,保留章节标签

deidentify_text

Safe Harbor 编辑:姓名、日期、SSN/MRN、电话、电子邮件、ZIP、年龄 > 89

资源以可寻址方式暴露相同数据(fhir://patients/{id}),因此客户端无需工具往返即可将完整患者记录附加为上下文。提示将我最常用的两个工作流——病历总结和以患者为基础的文献综述——编码为可复用模板。

HTTP transport with auth

CLINICAL_MCP_API_KEY=$(openssl rand -hex 32) clinical-mcp --transport http --port 8000

每个请求都必须携带 Authorization: Bearer <key>;服务器拒绝在 HTTP 上以未认证方式启动。stdio(默认)不需要密钥——传输层即信任边界。

Data

仓库在 data/sample/ 下附带 10 个精简的合成患者。如需更大的语料库:

python scripts/fetch_data.py --out data/full            # ~1,100 patients
CLINICAL_MCP_DATA_DIR=data/full clinical-mcp

--trim 将 bundle 精简为服务器实际读取的资源类型(Patient、Condition、MedicationRequest、Observation、AllergyIntolerance、Encounter、Immunization、Procedure、DiagnosticReport、CarePlan),并限制高容量类型。

De-identification: scope and limits

deidentify_text 是基于正则表达式的 Safe Harbor 筛查:它能捕获结构化临床文本中出现的标识符格式,并额外编辑存储中加载的每个患者姓名。它不是经过认证的去标识化流水线——没有敬语的自由文本姓名、拼写错误和罕见上下文中的标识符会漏过。对于真实的 PHI,你需要在上面叠加经过训练的 NER 处理(例如 Philter,或带人工审核的 LLM 处理);此工具是确定性的第一道过滤器,其按类别统计的计数使审计成本低廉。

What breaks at 500K documents a week

此服务器刻意按任务规模设计——基于合成语料库的参考实现。以下是生产负载下最先失效的部分,以及各自的升级路径:

  1. 内存存储。 启动时所有内容加载到 RAM;约 1 万患者没问题,约 10 万就不行了,启动时间线性增长。第一步修复:在同一个 FhirStore 接口后面使用带姓名、出生日期和疾病代码索引的 SQLite/DuckDB。真正的修复:将存储指向实际的 FHIR 端点(HAPI 或云 FHIR API),让工具成为 FHIR 搜索参数之上的薄翻译层。

  2. 每个 bundle 一个患者。 加载器假设 Synthea 的布局。混合 bundle 需要引用解析(subject.reference)而不是文件级分组。

  3. PubMed 速率限制。 3 请求/秒(有密钥时 10)交互式使用没问题,批量使用则毫无用处。在规模场景下,你需要一个以查询哈希为键、带 TTL 的本地缓存,以及批量 efetch(每次请求最多 200 个 PMID)而不是逐篇调用。

  4. 正则去标识化的召回率。 在每周 50 万文档的规模下,即使 99% 的召回率也会泄露数千个标识符。计数输出正是为此测量而设计:抽样、审计,并根据实测召回率设置门槛——然后在流水线中加入 NER 模型。

  5. 单进程 HTTP。 单进程下基于 uvicorn 的可流式 HTTP 只能服务一个团队,而非一个集群。水平扩展需要负载均衡器后面的无状态会话(存储是只读的,所以这几乎免费),以及网关处的每客户端速率限制。

Development

pip install -e ".[dev]"
pytest              # protocol-level + unit tests, PubMed mocked
ruff check .

Docker:

docker build -t clinical-mcp .
docker run --rm -i clinical-mcp                                   # stdio
docker run --rm -p 8000:8000 -e CLINICAL_MCP_API_KEY=secret \
  clinical-mcp --transport http --host 0.0.0.0

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors