Labsco
wso2 logo

FHIR MCP Server

★ 126

from wso2

FHIR MCP Server – helping you expose any FHIR Server or API as a MCP Server.

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#database#devops#git#maps

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

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

Copy & paste — that's it
"servers": {
 "fhir": {
 "type": "http",
 "url": "http://localhost:8000/mcp",
 }
}
Copy & paste — that's it
"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"
 }
 }
}
Copy & paste — that's it
"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.

  • 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:

Streamable HTTP STDIO SSE

Copy & paste — that's it
{
 "mcpServers": {
 "fhir": {
 "command": "npx",
 "args": [
 "-y",
 "mcp-remote",
 "http://localhost:8000/mcp"
 ]
 }
 }
}
Copy & paste — that's it
{
 "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"
 }
 }
 }
}
Copy & paste — that's it
{
 "mcpServers": {
 "fhir": {
 "command": "npx",
 "args": [
 "-y",
 "mcp-remote",
 "http://localhost:8000/sse"
 ]
 }
 }
}

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:

Streamable HTTP STDIO SSE

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

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

  • response_filter_fhirpaths: (Optional) An array of FHIRPath expressions (e.g., ["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"]) to apply to the resources in the response bundle.

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").

  • response_filter_fhirpaths: (Optional) An array of FHIRPath expressions (e.g., ["Patient.name", "Observation.valueQuantity"]) to filter the returned single resource (or entries when using custom operations like $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 linked Patient resource) and returns a concise profile containing available demographic fields such as id, name, and birthDate.

Development & Testing

Installing Development Dependencies

To run tests and contribute to development, install the test dependencies:

Using pip:

Copy & paste — that's it
# Install project in development mode with test dependencies
pip install -e '.[test]'

# Or install from requirements file
pip install -r requirements-dev.txt

Using uv:

Copy & paste — that's it
# Install development dependencies
uv sync --dev

Running Tests

The project includes a comprehensive test suite covering all major functionality:

Copy & paste — that's it
# Simple test runner
python run_tests.py

# Or direct pytest usage
PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server

Using pytest:

Copy & paste — that's it
pytest tests/

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.