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

资源以可寻址方式暴露相同数据（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