clinical-mcp

임상 워크플로우를 위한 MCP 서버: 합성 FHIR R4 환자 기록을 검색하고 요약하며, PubMed에서 문헌을 가져오고, 자유 텍스트를 비식별화합니다 — 모두 Claude(또는 모든 MCP 클라이언트)에서 가능합니다.

레퍼런스급 MCP 서버로 구축되었습니다: 전체 스펙 표면(tools, resources, prompts — 대부분의 공개 서버는 tools에서 멈춥니다)을 구현하고, 와이어 프로토콜을 검증하는 테스트 스위트를 포함하며, stdio 또는 인증된 streamable HTTP로 실행됩니다.

모든 환자 데이터는 합성 데이터이며, Synthea로 생성되었습니다. 이 프로젝트에는 실제 PHI가 존재하지 않습니다.

아키텍처

[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

빠른 시작

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 논문 3편을 가져와."

도구

Resources는 동일한 데이터를 주소 지정 가능한 형태(fhir://patients/{id})로 노출하므로, 클라이언트는 도구 왕복 없이 전체 환자 기록을 컨텍스트로 첨부할 수 있습니다. Prompts는 제가 가장 자주 사용하는 두 워크플로우(차트 요약 및 환자 기반 문헌 검토)를 재사용 가능한 템플릿으로 인코딩합니다.

인증이 포함된 HTTP 전송

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

모든 요청은 Authorization: Bearer <key>를携带해야 합니다. 서버는 HTTP에서 인증 없이 시작을 거부합니다. stdio(기본값)는 키가 필요 없습니다 — 전송 자체가 신뢰 경계입니다.

데이터

이 저장소는 data/sample/ 아래에 10명의 축소된 합성 환자를 포함합니다. 더 큰 코퍼스가 필요하다면:

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

--trim은 번들을 서버가 실제로 읽는 리소스 유형(Patient, Condition, MedicationRequest, Observation, AllergyIntolerance, Encounter, Immunization, Procedure, DiagnosticReport, CarePlan)으로 축소하고 대용량 유형의 수를 제한합니다.

비식별화: 범위와 한계

deidentify_text는 정규식 기반 Safe Harbor 스크리닝입니다. 구조화된 임상 텍스트에 나타나는 식별자 형식을 포착하고, 추가로 저장소에 로드된 모든 환자 이름을 편집합니다. 이는 인증된 비식별화 파이프라인이 아닙니다 — 호칭 없는 자유 텍스트 이름, 오타, 희귀 컨텍스트 식별자는 통과할 수 있습니다. 실제 PHI에는 훈련된 NER 패스(예: Philter, 또는 인간 검토가 포함된 LLM 패스)를 그 위에 계층화해야 합니다. 이 도구는 결정적 1차 필터이며, 카테고리별 개수 출력 덕분에 감사가 저렴합니다.

주당 50만 문서에서 무너지는 지점

이 서버는 의도적으로 그 역할에 맞게 크기가 조정되었습니다 — 합성 코퍼스에 대한 레퍼런스 구현입니다. 프로덕션 부하에서 가장 먼저 실패하는 부분과 각각의 업그레이드 경로는 다음과 같습니다:

1. 인메모리 저장소. 모든 것이 시작 시 RAM에 로드됩니다. 약 1만 명의 환자는 무난하지만, 약 10만 명은 무리이며 시작 시간은 선형적으로 증가합니다. 첫 번째 수정: 동일한 FhirStore 인터페이스 뒤에 이름, 생년월일, 질환 코드에 대한 인덱스가 있는 SQLite/DuckDB. 실제 수정: 저장소를 실제 FHIR 엔드포인트(HAPI 또는 클라우드 FHIR API)로 지정하고 도구를 FHIR 검색 파라미터 위의 얇은 변환 계층으로 만듭니다.

2. 번들당 환자 1명. 로더는 Synthea의 레이아웃을 가정합니다. 혼합 번들은 파일 수준 그룹화 대신 참조 해석(subject.reference)이 필요합니다.

3. PubMed 속도 제한. 초당 3회(키 사용 시 10회)는 대화형으로는 충분하지만 배치에서는 무용지물입니다. 볼륨이 커지면 쿼리 해시를 키로 하는 TTL 기반 로컬 캐시와 문서별 호출 대신 배치 efetch(요청당 최대 200 PMID)가 필요합니다.

4. 정규식 비식별화 재현율. 주당 50만 문서에서 99% 재현율도 수천 개의 식별자를 누출합니다. 개수 출력은 정확히 이 측정을 위해 설계되었습니다: 샘플링, 감사, 측정된 재현율에 대한 게이팅 — 그런 다음 파이프라인에 NER 모델을 배치합니다.

5. 단일 프로세스 HTTP. uvicorn의 단일 프로세스에서 streamable HTTP는 팀 규모는 감당하지만 플릿 규모는 아닙니다. 수평 확장에는 로드 밸런서 뒤의 무상태 세션(저장소가 읽기 전용이므로 대부분 무료)과 게이트웨이에서의 클라이언트별 속도 제한이 필요합니다.

개발

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

라이선스

MIT