Connects users to WSO2's Discord community for support and collaboration on the FHIR MCP server project
Enables containerized deployment and execution of the FHIR MCP server for consistent, isolated environments
Supports environment variable configuration through .env files for FHIR server credentials and MCP server settings
Implements OpenID authentication flows as part of SMART-on-FHIR security standards for secure healthcare data access
Provides installation and distribution of the FHIR MCP server package through PyPI's package management system
Provides comprehensive testing framework with 100+ tests covering async operations, OAuth flows, and FHIR API interactions
Built as a Python-based MCP server for integrating with FHIR healthcare APIs and managing clinical data
Displays project status badges for license, community support, and social media links in the documentation
Provides community support channel for WSO2-related questions and technical assistance with the FHIR MCP server
Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs
Table of Contents
- Overview
- Demo
- Core Features
- Prerequisites
- Installation
- Integration with MCP Clients
- Configuration
- Tools
- Development & Testing
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
- 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, by cloning this repository or by running as a docker container.
Installing using PyPI Package
- Configure Environment Variables: To run the server, you must set
FHIR_SERVER_BASE_URL
. If you plan to use authorization, you'll also need to configureFHIR_SERVER_CLIENT_ID
,FHIR_SERVER_CLIENT_SECRET
, andFHIR_SERVER_SCOPES
. By default, the MCP server will listen on http://localhost:8000. You can customize the host and port by settingFHIR_MCP_HOST
andFHIR_MCP_PORT
respectively. You can set these by exporting them as environment variables like below or by creating a.env
file (referencing.env.example
). - Install the PyPI package and run the server If you are exposing a FHIR server with no security:else;
Installing from Source
- Clone the repository:
- Create a virtual environment and install dependencies:Or with pip:
- Configure Environment Variables:
Copy the example file and customize if needed:
- Run the server:
Installing using Docker
You can run the MCP server using Docker for a consistent, isolated environment.
- Build the Docker Image
- 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. - Run the ContainerThis will start the server and expose it on port 8000. Adjust the port mapping as needed.
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 User Settings (JSON) file in VS Code (> V1.101). You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).
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:
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:
- 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.
Configuration
CLI Options
You can customize the behavior of the MCP server using the following command-line flags:
- --transport
- Description: Specifies the transport protocol used by the MCP server to communicate with clients.
- Accepted values: stdio, sse, streamable-http
- Default: streamable-http
- --log-level
- Description: Sets the logging verbosity level for the server.
- Accepted values: DEBUG, INFO, WARN, ERROR (case-insensitive)
- Default: INFO
- --disable-auth
- Description: Disables the security of the MCP Server. Allows you to connect with openly available FHIR servers.
- Type: Flag (no value required)
- Default: False (authentication enabled)
- --help
- Description: Displays a help message with available server options and exits.
- Usage: Automatically provided by the command-line interface.
Sample Usages:
Environment Variables
MCP Server Configurations:
FHIR_MCP_HOST
: The hostname or IP address the MCP server should bind to (e.g.,localhost
for local-only access, or0.0.0.0
for 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_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 openid
to enable retrieval of user context for theget_user
tool. If these two scopes are not configured, theget_user
tool 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.
Tools
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"}).
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").
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").
get_user
: Retrieves the currently authenticated user's FHIR resource (for example the linkedPatient
resource) and returns a concise profile containing available demographic fields such asid
,name
, andbirthDate
.
Development & Testing
Installing Development Dependencies
To run tests and contribute to development, install the test dependencies:
Using pip:
Using uv:
Running Tests
The project includes a comprehensive test suite covering all major functionality:
Using pytest:
This will discover and run all tests in the tests/
directory.
Test Features:
- 100+ tests with comprehensive coverage
- Full async/await support using pytest-asyncio
- Complete mocking of HTTP requests and external dependencies
- Coverage reporting with terminal and HTML output
- Fast execution with no real network calls
The test suite includes:
- Unit tests: Core functionality testing
- Integration tests: Component interaction validation
- Edge case coverage: Error handling and validation scenarios
- Mocked OAuth flows: Realistic authentication testing
Coverage reports are generated in htmlcov/index.html
for detailed analysis.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables seamless integration with FHIR APIs for healthcare applications, allowing users to search, retrieve, create, update, and analyze clinical information through natural language interactions. Supports SMART-on-FHIR authentication and works with various healthcare systems like EPIC and HAPI FHIR servers.