FHIR MCP Server
OfficialExpose any FHIR server or API as MCP tools to search, read, and write clinical data with SMART-on-FHIR auth.
Add to your client
Copy the config for your MCP client and paste it into its config file.
uvx fhir-mcp-serverPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"fhir-mcp-server": {
"command": "uv",
"args": [
"--directory",
"/path/to/fhir-mcp-server",
"run",
"fhir-mcp-server",
"--transport",
"stdio"
],
"env": {
"FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
}
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.8+
- uv (for dependency management)
- An accessible FHIR API server (e.g. HAPI FHIR, Epic sandbox)
About FHIR MCP Server
An MCP server that connects AI/LLM tools to healthcare data via FHIR APIs. It acts as a bridge to any accessible FHIR server, supporting search, read, create, update, and delete interactions plus capability discovery and authenticated user lookup. Transports include stdio, SSE, and streamable HTTP, with SMART-on-FHIR OAuth 2.0 authentication and optional FHIRPath response filtering.
Tools & capabilities (7)
get_capabilitiesRetrieves metadata about a specified FHIR resource type, including its supported search parameters and custom operations. Parameter: type (FHIR resource type name, e.g. Patient, Observation, Encounter).
searchExecutes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources. Parameters: type, searchParam (map of search parameter names to values), and optional response_filter_fhirpaths (array of FHIRPath expressions to filter the response bundle).
readPerforms a FHIR read interaction to retrieve a single resource instance by type and resource ID, optionally refined with search parameters or custom operations (e.g. $everything). Parameters: type, id, searchParam, operation, and optional response_filter_fhirpaths.
createExecutes a FHIR create interaction to persist a new resource of the specified type. Parameters: type, payload (full FHIR resource body), searchParam, and operation (e.g. $evaluate).
updatePerforms a FHIR update interaction by replacing an existing resource instance's content with the provided payload. Parameters: type, id, payload, searchParam, and operation (e.g. $lastn).
deleteExecutes a FHIR delete interaction on a specific resource instance. Parameters: type, id, searchParam, and operation (e.g. $expand).
get_userRetrieves the currently authenticated user's FHIR resource (e.g. the linked Patient resource) and returns a concise profile with available demographic fields such as id, name, and birthDate. Requires the fhirUser and openid scopes.
When to use it
- Letting an LLM search and retrieve clinical information (patients, observations, conditions, etc.) from a FHIR server in natural language
- Creating, updating, or deleting FHIR resources through an AI assistant or MCP client
- Prototyping FHIR integrations against a local HAPI FHIR server via the bundled Docker Compose setup
- Connecting to EHR sandboxes such as Epic using the full SMART-on-FHIR OAuth 2.0 authorization flow
- Reducing LLM context/payload size by filtering FHIR read and search responses with FHIRPath expressions
Security notes
Uses SMART-on-FHIR / OAuth 2.0 authorization code grant by default; configure FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET, and FHIR_SERVER_SCOPES, or set FHIR_SERVER_ACCESS_TOKEN to use a token directly. Set FHIR_SERVER_DISABLE_AUTHORIZATION=True for public FHIR servers. The README notes that when running locally via Docker or Docker Compose, authorization should currently be disabled (FHIR_SERVER_DISABLE_AUTHORIZATION=True) pending a future fix. Handles protected health information (PHI) — secure FHIR credentials and access tokens accordingly.
FHIR MCP Server FAQ
Which FHIR servers does it work with?
Any accessible FHIR API server. The README demonstrates a public HAPI FHIR server (no auth flow needed) and the Epic EHR sandbox (full OAuth 2.0 authorization code grant). Set FHIR_SERVER_BASE_URL to the target server.
How is authentication handled?
It uses SMART-on-FHIR / OAuth 2.0 authorization code grant by default (configure FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET, FHIR_SERVER_SCOPES). You can bypass the flow by setting FHIR_SERVER_ACCESS_TOKEN directly, or disable authorization entirely with FHIR_SERVER_DISABLE_AUTHORIZATION=True for public servers.
What transports are supported?
stdio, SSE, and streamable HTTP. The default transport is streamable-http; choose with the --transport CLI flag. By default the server listens on http://localhost:8000.
How do I install it?
Run the PyPI package with `uvx fhir-mcp-server`, install from source with uv/pip, or use Docker. A docker-compose.yml is provided to spin up the MCP server alongside a HAPI FHIR server and PostgreSQL for an instant dev environment.
Can I reduce the size of FHIR responses?
Yes. The read and search tools accept an optional response_filter_fhirpaths array of FHIRPath expressions (e.g. ["Patient.name", "Patient.birthDate"]) so only the needed fields are returned.
Alternatives to FHIR MCP Server
Compare all alternatives →
Official MCP server providing persistent, file-backed knowledge-graph memory across sessions.
Structured step-by-step reasoning tool for breaking problems into revisable thought sequences.
Fully managed remote server for AWS docs, blogs, What's-New and Well-Architected guidance — no key.
Compare FHIR MCP Server with: