fhir-mcp-suite
The fhir-mcp-suite server provides a comprehensive FHIR R4 interface for reading, searching, paginating, and validating clinical resources, with additional terminology and clinical reasoning capabilities.
fhir_capabilities: Retrieve a summary of the FHIR server's CapabilityStatement, including FHIR version, software info, supported resource types, and available search parameters.fhir_read: Fetch a single FHIR R4 resource (e.g., Patient, Observation, Medication) by resource type and logical ID, returning the full resource as JSON.fhir_search: Search any FHIR R4 resource type using standard FHIR search parameters, returning a FHIR Bundle with matching entries.fhir_search_next: Paginate through large result sets by passing the_next_urlfrom a previous Bundle.validate_against_profile: Validate a FHIR R4 resource against a StructureDefinition profile using the HAPI validator, with support for US Core, IPS, and base FHIR R4 conformance — returns conformance status, error count, and detailed issues.Terminology services: Perform unified lookups across LOINC, SNOMED, RxNorm, and ICD-10, and expand ValueSets.
Clinical reasoning: Check for drug interactions (via OpenFDA), perform dose checks, and identify potential allergy conflicts.
fhir-mcp-suite
Three coherent MCP servers for clinical AI — FHIR R4, terminologies, and clinical reasoning.
What's in the suite
Server | Status | Install | What it does |
mcp-fhir | ✅ v1.1.1 on PyPI |
| FHIR R4 read/search + HAPI profile validation |
mcp-terminology | ✅ v1.0 on PyPI |
| Unified LOINC / SNOMED / RxNorm / ICD-10 lookup + ValueSet expansion |
mcp-clinical-reasoner | ✅ v1.0 on PyPI |
| Drug interactions (OpenFDA), dose check, allergy conflicts |
Related MCP server: atlas_mcp
Why this suite is different
Every FHIR MCP server available today (June 2026) is a read proxy — they retrieve resources but
never tell you whether the resource is valid. mcp-fhir adds HAPI profile validation as a
first-class MCP tool. Composing fhir_read → validate_against_profile in one Claude session
enables clinical AI pipelines that are actually safe.
Three sharp differentiators:
Profile validation built into
mcp-fhir— HAPI validator sidecar, US Core + IPS profiles supported out of the boxComposable suite — three coherent servers sharing one install, one config convention, one eval harness
Production rigor — latency benchmarks, golden-query eval suite, structured JSON logs,
/health+ LangFuse traces
Quick start — mcp-fhir
# 1-command install (requires Python 3.12+)
uvx mcp-fhir
# Validate a Patient against US Core
# (requires HAPI validator sidecar — see docker-compose.yml)
uvx mcp-fhir --transport sse # or set MCP_TRANSPORT=sseClaude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
(Windows: %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"fhir": {
"command": "uvx",
"args": ["mcp-fhir"],
"env": {
"FHIR_BASE_URL": "https://hapi.fhir.org/baseR4"
}
},
"terminology": {
"command": "uvx",
"args": ["mcp-terminology"]
},
"clinical-reasoner": {
"command": "uvx",
"args": ["mcp-clinical-reasoner"]
}
}
}Local dev stack
# Start HAPI FHIR + validator + Postgres
docker compose up hapi-fhir hapi-validator postgres
# Install workspace
uv sync
# Run unit tests
uv run pytest -m "not integration and not eval"
# Run mcp-fhir locally (stdio, points at local HAPI)
FHIR_BASE_URL=http://localhost:8081/fhir \
HAPI_VALIDATOR_URL=http://localhost:8082 \
uv run mcp-fhirRepo layout
fhir-mcp-suite/
├── packages/
│ ├── mcp-fhir/ # PyPI: mcp-fhir ✅ v1.1
│ ├── mcp-terminology/ # PyPI: mcp-terminology ✅ v1.0
│ └── mcp-clinical-reasoner/ # PyPI: mcp-clinical-reasoner ✅ v1.0
├── shared/ # structlog, LangFuse, base Pydantic models, eval harness
├── evals/ # golden query sets per server
├── docs/ # MkDocs Material site
├── .github/workflows/ # ci.yml (matrix) + release.yml (per-package PyPI on tag)
├── docker-compose.yml # all 3 + HAPI validator + Postgres
├── pyproject.toml # uv workspace root
└── mkdocs.ymlReleases
Package | Version | Released |
| v1.1 | June 2026 |
| v1.0 | June 2026 |
| v1.0 | June 2026 |
Contributing
See CONTRIBUTING.md. Apache-2.0 licensed — PRs welcome.
Available Tools
5 toolsfhir_capabilitiesA
Retrieve a summary of the FHIR server's CapabilityStatement: FHIR version, software, supported resource types, and available search parameters. Call this first to understand what the server supports.
Inputs: no named parameters.
fhir_readA
Read a single FHIR R4 resource by type and logical ID. Returns the full resource JSON.
Inputs: resource_type (required), resource_id (required).
fhir_searchB
Search a FHIR R4 resource type. Returns a FHIR Bundle (searchset) with matching entries.
Inputs: resource_type (required), params.
fhir_search_nextA
Follow a Bundle pagination link returned by fhir_search. Pass the '_next_url' value from the previous search result. Returns the next page as a FHIR Bundle, again with '_next_url' if more pages exist.
Inputs: next_url (required).
validate_against_profileA
Validate a FHIR R4 resource against a StructureDefinition profile using the HAPI validator. Supports US Core and IPS profiles as well as base FHIR R4 conformance. Returns conformance status, error count, and issue details.
Inputs: resource (required), profile, fhir_version.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool serves a unique and clearly distinct purpose: capabilities for metadata, read for single resource retrieval, search for querying, search_next for pagination, and validate for conformance checking. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., fhir_read, fhir_search). The 'fhir_' prefix is used uniformly, and each name clearly describes the action and domain.
With 5 tools, the set is appropriately scoped for a focused FHIR read/search/validation suite. It is not excessive, and each tool provides essential functionality. A slightly higher count could cover write operations, but the current number is reasonable.
The tool set covers capabilities, read, search, pagination, and validation, but lacks write operations (create, update, delete), history, and transaction support. For a full FHIR interaction, these missing operations are notable gaps, though the validation focus partially justifies the omission.
Maintenance
Related MCP Connectors
MCP gateway federating 22 biomedical MCP servers behind one endpoint: gnomAD, ClinVar, HPO, VEP.
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
Pharmacogenomics for AI agents: cited drug–gene, gene and rsID lookups plus a medication screen.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA clean-room SHARP-on-MCP compliant FHIR R4 MCP server that enables AI agents to interact with any FHIR R4 endpoint using SHARP context headers, without server-side OAuth. It provides clinical tools, lab results, imaging, and interactive MCP-UI dashboards.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that brings AI-powered search and conversation to your FHIR clinical documents.21 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceClinical decision-support MCP server that lets AI agents reason over live FHIR patient data for medication review, appointment scheduling, and care gap identification.9,324 npmMIT
- AlicenseAqualityAmaintenanceOpen-source guardrails between AI agents and FHIR clinical data — PHI redaction, immutable audit, step-up auth, tenant isolation. MCP server + OpenAI/Gemini adapters. A healthclaw.io project.2934MIT