FHIR MCP Server

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

Table of Contents

• 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
• Core Features
• Prerequisites
• Installation
• Installing using PyPI Package
• Installing from Source
• Installing using Docker
• Running the MCP Server with Docker
• Using Docker Compose with WSO2 FHIR Server
• Configuring any FHIR Server
• Integration with MCP Clients
• VS Code
• Claude Desktop
• MCP Inspector
• Configuration
• CLI Options
• Environment Variables
• Tools
• Development \& Testing
• Installing Development Dependencies
• Running Tests

Overview

The FHIR MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with FHIR APIs. Designed for developers, integrators, and healthcare innovators, this server acts as a bridge between modern AI/LLM tools and healthcare data, making it easy to search, retrieve, and analyze clinical information.

Demo

Demo with HAPI FHIR server

This video showcases the MCP server's functionality when connected to a public HAPI 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

Demo with EPIC Sandbox

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

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

Core Features

• MCP-compatible transport: Serves FHIR via stdio, SSE, or streamable HTTP

• SMART-on-FHIR based authentication support: Securely authenticate with FHIR servers and clients

• Response Filtering using FHIRPath: Filter resources and bundles returned by read and search operations using custom FHIRPath expressions to retrieve only the fields needed for the task, reducing payload sizes.

• Tool integration: Integratable with any MCP client such as VS Code, Claude Desktop, and MCP Inspector

Prerequisites

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

Installation

You can use the FHIR MCP Server by installing our Python package, or by cloning this repository.

Installing using PyPI Package

1. Configure Environment Variables:

To run the server, you must set FHIR_SERVER_BASE_URL.

• To enable authorization: Set FHIR_SERVER_BASE_URL, FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET, and FHIR_SERVER_SCOPES. Authorization is enabled by default.
• To disable authorization: Set FHIR_SERVER_DISABLE_AUTHORIZATION to True.

By default, the MCP server runs on [http://localhost:8000](http://localhost:8000), and you can customize the host and port using FHIR_MCP_HOST and FHIR_MCP_PORT.

You can set these by exporting them as environment variables like below or by creating a .env file (referencing .env.example).

`bash 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" `

1. Install the PyPI package and run the server

bash uvx fhir-mcp-server

Installing from Source

1. Clone the repository: bash git clone cd

1. Create a virtual environment and install dependencies: bash uv venv source .venv/bin/activate uv pip sync requirements.txt Or with pip: bash python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

1. Configure Environment Variables: Copy the example file and customize if needed: bash cp .env.example .env

1. Run the server: bash uv run fhir-mcp-server

Installing using Docker

Running the MCP Server with Docker

You can run the MCP server using Docker for a consistent, isolated environment.

Note on Authorization: When running the MCP server locally via Docker or Docker Compose, authorization should be disabled by setting the environment variable, FHIR_SERVER_DISABLE_AUTHORIZATION=True . This would be fixed in the future releases.

1. Build the Docker Image or pull the docker image from the container registry:

• Build from source: bash docker build -t fhir-mcp-server .
• Pull from GitHub Container Registry: bash docker pull ghcr.io/wso2/fhir-mcp-server:latest latest is built from the main branch. To use a release, pull its version tag instead, for example ghcr.io/wso2/fhir-mcp-server:0.11.0.

1. Configure Environment Variables

Copy the example environment file and edit as needed:

`bash cp .env.example .env

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

`

Alternatively, you can pass environment variables directly with -e flags or use Docker secrets for sensitive values. See the Configuration section for details on available environment variables.

1. Run the Container

bash docker run --env-file .env -p 8000:8000 ghcr.io/wso2/fhir-mcp-server:latest

This will start the server and expose it on port 8000. Adjust the port mapping as needed.

Using Docker Compose with WSO2 FHIR Server

For a quick setup that includes both the FHIR MCP server and the WSO2 FHIR Server (with PostgreSQL), use the provided docker-compose.yml. This sets up an instant development environment for testing FHIR operations.

1. Prerequisites:

• Docker and Docker Compose installed.

1. Set the Database Credentials:

Copy the example environment file and set DB_PASSWORD in .env. If you already have a .env, add the DB_USER, DB_PASSWORD and DB_NAME lines from .env.example to it instead.

   cp .env.example .env

Docker Compose reads .env automatically. DB_USER and DB_NAME default to postgres if not set. .env is excluded from Git; use a secrets manager for production deployments.

1. Run the Stack:

   docker compose up -d

This command will:

• Start a PostgreSQL database container.
• Launch the FHIR Server (connected to PostgreSQL) listening on http://localhost:8080/fhir/r4.
• Build and run the FHIR MCP server container listening on http://localhost:8000, with FHIR_SERVER_BASE_URL set to http://wso2-fhir-server:8080/fhir/r4.

1. Access the Services:

• FHIR MCP Server: http://localhost:8000
• FHIR Server: http://localhost:8080/fhir/r4
• To stop run docker compose down.

docker compose down removes the database data; use docker compose stop to keep it between runs.

1. Configure Additional Environment Variables:

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

Configuring any FHIR Server

To use a different FHIR server, run the FHIR MCP server container with FHIR_SERVER_BASE_URL pointing to that server. The example below uses the HAPI FHIR server. Stop the default stack first if it's already running (docker compose down), as both use ports 8000 and 8080.

1. Create a network and start the HAPI FHIR server:

   docker network create fhir-network

docker run -d --name hapi-fhir-server --network fhir-network -p 127.0.0.1:8080:8080 docker.io/hapiproject/hapi:v8.4.0-2

HAPI FHIR listens on http://localhost:8080/fhir. This uses its built-in database, so data is lost when the container is removed.

1. Build and run the FHIR MCP server container:

   docker build -t fhir-mcp-server .

docker run -d --name fhir-mcp-server-hapi --network fhir-network -p 127.0.0.1:8000:8000 -e FHIR_SERVER_BASE_URL=http://hapi-fhir-server:8080/fhir -e FHIR_MCP_HOST=0.0.0.0 -e FHIR_SERVER_DISABLE_AUTHORIZATION=True fhir-mcp-server

The FHIR MCP server listens on http://localhost:8000.

1. Stop and clean up:

   docker rm -f fhir-mcp-server-hapi hapi-fhir-server

docker network rm fhir-network

For any other FHIR server, set FHIR_SERVER_BASE_URL to its base URL. If the FHIR server runs on your host rather than in Docker, use http://host.docker.internal: /... instead of localhost. On Linux, also add --add-host=host.docker.internal:host-gateway to the docker run command, and make sure the FHIR server listens on an address reachable from containers (for example 0.0.0.0, not only 127.0.0.1).

Integration with MCP Clients

The FHIR MCP Server is designed for seamless integration with various MCP clients.

VS Code

Add the following JSON block to your MCP configuration file in VS Code (> V1.104). You can do this by pressing Ctrl + Shift + P and typing MCP: Open User Configuration.

Streamable HTTP STDIO SSE

"servers": {

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

</td>

"servers": {

"fhir": { "command": "uv", "args": [ "-