wso2/fhir-mcp-server

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).
2. **Install the PyPI package and run the server**
Installing from Source
1. **Clone the repository:**
2. **Create a virtual environment and install dependencies:**
Or with pip:
3. **Configure Environment Variables:**
Copy the example file and customize if needed:
4. **Run the 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:
* Pull from GitHub Container Registry:
2. Configure Environment Variables
Copy the example environment file and edit as needed:
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