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 HAPI 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, 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"
   

2. Install the PyPI package and run the server

   uvx fhir-mcp-server
   

Installing from Source

1. Clone the repository:

   git clone <repository_url>
   cd <repository_directory>
   

2. 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
   

3. Configure Environment Variables: Copy the example file and customize if needed:

   cp .env.example .env
   

4. 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.

1. 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
     

2. 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.

3. 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.

1. Prerequisites:

   • Docker and Docker Compose installed.

2. 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.

3. Access the Services:

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

4. 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.

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

Claude Desktop

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

• L