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

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

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, 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).
```
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"
```
Install the PyPI package and run the server
```
uvx fhir-mcp-server
```

Installing from Source

Clone the repository:

git clone <repository_url>
cd <repository_directory>

Create a virtual environment and install dependencies:

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

Or with pip:

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

Configure Environment Variables: Copy the example file and customize if needed:
```
cp .env.example .env
```
Run the server:
```
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.

Build the Docker Image or pull the docker image from the container registry:
- Build from source:
```
docker build -t fhir-mcp-server .
```
- Pull from GitHub Container Registry:
```
docker pull wso2/fhir-mcp-server:latest
```
Configure Environment Variables

Copy the example environment file and edit as needed:
```
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.
Run the Container
```
docker run --env-file .env -p 8000:8000 fhir-mcp-server
```
This will start the server and expose it on port 8000. Adjust the port mapping as needed.

Using Docker Compose with HAPI FHIR Server

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

Prerequisites:
- Docker and Docker Compose installed.
Run the Stack:
```
docker-compose up -d
```
This command will:
- Start a PostgreSQL database container.
- Launch the HAPI FHIR server (connected to PostgreSQL) listening on http://localhost:8080.
- Build and run the FHIR MCP server container listening on http://localhost:8000, with FHIR_SERVER_BASE_URL set to http://hapi-r4-postgresql:8080/fhir.
Access the Services:
- FHIR MCP Server: http://localhost:8000
- HAPI FHIR Server: http://localhost:8080
- To stop run docker-compose down.
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.

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.

<table> <tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr> <tr valign=top> <td>

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

</td> <td>

"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"
        }
    }
}

</td> <td>

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

</td> </tr> </table>

Claude Desktop

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
Open the claude_desktop_config.json file in any text editor. Replace its contents with the following JSON block to register the MCP server:

<table> <tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr> <tr valign=top> <td>

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

</td> <td>

{
    "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"
            }
        }
    }
}

</td> <td>

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

</td> </tr> </table>

MCP Inspector

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

Open a terminal and run the following command:

npx -y @modelcontextprotocol/inspector
In the MCP Inspector interface:

<table> <tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr> <tr valign=top> <td>

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

</td>

…

Fhir

Installation

Configuration

How to use

README

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 HAPI FHIR Server

Integration with MCP Clients

VS Code

Claude Desktop

MCP Inspector

You might also like