FHIR

Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs

- Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs

- Table of Contents
- Overview
- Demo

- Demo with HAPI FHIR server
- Demo with EPIC Sandbox

- Installing using PyPI Package
- Installing from Source
- Installing using Docker

- Running the MCP Server with Docker
- Using Docker Compose with HAPI FHIR Server

- Installing Development Dependencies
- Running Tests

This video showcases the MCP server's functionality when connected to a publicHAPI FHIR server. This example showcases direct interaction with an open FHIR server that does not require an authorization flow.

https://github.com/user-attachments/assets/cc6ac87e-8329-4da4-a090-2d76564a3abf

This video showcases the MCP server's capabilities within theEpic EHR ecosystem. It demonstrates the complete OAuth 2.0 Authorization Code Grant flow.

https://github.com/user-attachments/assets/96b433f1-3e53-4564-8466-65ab48d521de

- Python 3.8+
- uv(for dependency management)
- An accessible FHIR API server.

By default, the MCP server runs onhttp://localhost:8000, and you can customize the host and port usingFHIR_MCP_HOSTandFHIR_MCP_PORT.

export FHIR_SERVER_BASE_URL="" export FHIR_SERVER_CLIENT_ID="" export FHIR_SERVER_CLIENT_SECRET="" export FHIR_SERVER_SCOPES="" export FHIR_MCP_HOST="localhost" export FHIR_MCP_PORT="8000"

git clone <repository_url> cd <repository_directory>

uv venv source .venv/bin/activate uv pip sync requirements.txt

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

docker build -t fhir-mcp-server .

cp .env.example .env # Edit .env to set your FHIR server, client credentials, etc.

Alternatively, you can pass environment variables directly with-eflags or use Docker secrets for sensitive values. See theConfigurationsection for details on available environment variables.

docker run --env-file .env -p 8000:8000 fhir-mcp-server

- Start a PostgreSQL database container.
- Launch the HAPI FHIR server (connected to PostgreSQL) listening onhttp://localhost:8080.
- Build and run the FHIR MCP server container listening onhttp://localhost:8000, withFHIR_SERVER_BASE_URLset tohttp://hapi-r4-postgresql:8080/fhir.

- FHIR MCP Server:http://localhost:8000
- HAPI FHIR Server:http://localhost:8080
- To stop rundocker-compose down.

If you need to customize OAuth or other settings, adjust the env variables in thedocker-compose.yml. The compose file sets basic configuration; refer to theConfigurationsection for full options.

"servers": { "fhir": { "type": "http", "url": "http://localhost:8000/mcp", } }

"servers": { "fhir": { "command": "uv", "args": [ "--directory", "/path/to/fhir-mcp-server", "run", "fhir-mcp-server", "--transport", "stdio" ], "env": { "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token" } } }

"servers": { "fhir": { "type": "sse", "url": "http://localhost:8000/sse", } }

Add the following JSON block to your Claude Desktop settings to connect to your local MCP server.

- Launch the Claude Desktop app, click on the Claude menu in the top bar, and select "Settings…".
- In the Settings pane, click “Developer” in the left sidebar. Then click "Edit Config". This will open your configuration file in your file system. If it doesn’t exist yet, Claude will create one automatically at:

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "fhir": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:8000/mcp" ] } } }

{ "mcpServers": { "fhir": { "command": "uv", "args": [ "--directory", "/path/to/fhir-mcp-server", "run", "fhir-mcp-server", "--transport", "stdio" ], "env": { "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token" } } } }

{ "mcpServers": { "fhir": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:8000/sse" ] } } }

Follow these steps to get the MCP Inspector up and running:

-

Open a terminal and run the following command:

- Transport Type:Streamable HTTP
- URL:http://localhost:8000/mcp

- Transport Type:STDIO
- Command:uv
- Arguments:--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio

- Transport Type:SSE
- URL:http://localhost:8000/sse

Make sure your MCP server is already running and listening on the above endpoint.

Once connected, MCP Inspector will allow you to visualize tool invocations, inspect request/response payloads, and debug your tool implementations easily.

You can customize the behavior of the MCP server using the following command-line flags:

- Description: Specifies the transport protocol used by the MCP server to communicate with clients.
- Accepted values: stdio, sse, streamable-http
- Default: streamable-http

- Description: Sets the logging verbosity level for the server.
- Accepted values: DEBUG, INFO, WARN, ERROR (case-insensitive)
- Default: INFO

- Description: Displays a help message with available server options and exits.
- Usage: Automatically provided by the command-line interface.

uv run fhir-mcp-server --transport streamable-http --log-level DEBUG uv run fhir-mcp-server --help

- FHIR_MCP_HOST: The hostname or IP address the MCP server should bind to (e.g.,localhostfor local-only access, or0.0.0.0for all interfaces).
- FHIR_MCP_PORT: The port on which the MCP server will listen for incoming client requests (e.g.,8000).
- FHIR_MCP_SERVER_URL: If set, this value will be used as the server's base URL instead of generating it from host and port. Useful for custom URL configurations or when behind a proxy.
- FHIR_MCP_REQUEST_TIMEOUT: Timeout duration in seconds for requests from the MCP server to the FHIR server (default:30).

MCP Server OAuth2 with FHIR server Configuration (MCP Client ↔ MCP Server):These variables configure the MCP client's secure connection to the MCP server, using the OAuth2 authorization code grant flow with a FHIR server.

- FHIR_SERVER_CLIENT_ID: The OAuth2 client ID used to authorize MCP clients with the FHIR server.
- FHIR_SERVER_DISABLE_AUTHORIZATION: If set toTrue, disables authorization checks on the MCP server, allowing connections to publicly accessible FHIR servers.
- FHIR_SERVER_CLIENT_SECRET: The client secret corresponding to the FHIR client ID. Used during token exchange.
- FHIR_SERVER_BASE_URL: The base URL of the FHIR server (e.g.,https://hapi.fhir.org/baseR4). This is used to generate tool URIs and to route FHIR requests.
- FHIR_SERVER_SCOPES: A space-separated list of OAuth2 scopes to request from the FHIR authorization server (e.g.,user/Patient.read user/Observation.read). AddfhirUser openidto enable retrieval of user context for theget_usertool. If these two scopes are not configured, theget_usertool returns an empty result because the ID token lacks the user's FHIR resource reference.
- FHIR_SERVER_ACCESS_TOKEN: The access token to use for authenticating requests to the FHIR server. If this variable is set, the server will bypass the OAuth2 authorization flow and use this token directly for all requests.

[!NOTE]FHIR_SERVER_ACCESS_TOKENis intended for localstdiomode deployments only, as a convenience to bypass interactive OAuth authentication. Do not use this variable when the MCP server is exposed over a network or the public internet.

-

get_capabilities: Retrieves metadata about a specified FHIR resource type, including its supported search parameters and custom operations.

- type: The FHIR resource type name (e.g., "Patient", "Observation", "Encounter")

search: Executes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources.

- type: The FHIR resource type name (e.g., "MedicationRequest", "Condition", "Procedure").
- searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"family":"Simpson","birthdate":"1956-05-12"}).
- response_filter_fhirpaths: (Optional) An array of FHIRPath expressions (e.g.,["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"]) to apply to the resources in the response bundle.

read: Performs a FHIR "read" interaction to retrieve a single resource instance by its type and resource ID, optionally refining the response with search parameters or custom operations.

- type: The FHIR resource type name (e.g., "DiagnosticReport", "AllergyIntolerance", "Immunization").
- id: The logical ID of a specific FHIR resource instance.
- searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"device-name":"glucometer"}).
- operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$everything").
- response_filter_fhirpaths: (Optional) An array of FHIRPath expressions (e.g.,["Patient.name", "Observation.valueQuantity"]) to filter the returned single resource (or entries when using custom operations like$everything).

create: Executes a FHIR "create" interaction to persist a new resource of the specified type.

- type: The FHIR resource type name (e.g., "Device", "CarePlan", "Goal").
- payload: A JSON object representing the full FHIR resource body to be created.
- searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"address-city":"Boston"}).
- operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$evaluate").

update: Performs a FHIR "update" interaction by replacing an existing resource instance's content with the provided payload.

- type: The FHIR resource type name (e.g., "Location", "Organization", "Coverage").
- id: The logical ID of a specific FHIR resource instance.
- payload: The complete JSON representation of the FHIR resource, containing all required elements and any optional data.
- searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"patient":"Patient/54321","relationship":"father"}).
- operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$lastn").

delete: Execute a FHIR "delete" interaction on a specific resource instance.

- type: The FHIR resource type name (e.g., "ServiceRequest", "Appointment", "HealthcareService").
- id: The logical ID of a specific FHIR resource instance.
- searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"category":"laboratory","issued:"2025-05-01"}).
- operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$expand").