Fhir Mcp Server

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

[](https://github.com/wso2/fhir-mcp-server/blob/main/LICENSE) [](https://stackoverflow.com/questions/tagged/wso2) [](https://discord.com/invite/wso2) [](https://twitter.com/intent/follow?screenname=wso2) [](https://spark.entire.vc/assets/vb-fhir?utmsource=github&utmmedium=readme) [](https://spark.entire.vc/assets/vb-fhir?utmsource=github&utm_medium=readme)

Table of Contents

• [Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs](#model-context-protocol-mcp-server-for-fast-healthcare-interoperability-resources-fhir-apis)
• [Table of Contents](#table-of-contents)
• [Overview](#overview)
• [Demo](#demo)
• [Demo with HAPI FHIR server](#demo-with-hapi-fhir-server)
• [Demo with EPIC Sandbox](#demo-with-epic-sandbox)
• [Core Features](#core-features)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Installing using PyPI Package](#installing-using-pypi-package)
• [Installing from Source](#installing-from-source)
• [Installing using Docker](#installing-using-docker)
• [Running the MCP Server with Docker](#running-the-mcp-server-with-docker)
• [Using Docker Compose with HAPI FHIR Server](#using-docker-compose-with-hapi-fhir-server)
• [Integration with MCP Clients](#integration-with-mcp-clients)
• [VS Code](#vs-code)
• [Claude Desktop](#claude-desktop)
• [MCP Inspector](#mcp-inspector)
• [Configuration](#configuration)
• [CLI Options](#cli-options)
• [Environment Variables](#environment-variables)
• [Tools](#tools)
• [Development \& Testing](#development--testing)
• [Installing Development Dependencies](#installing-development-dependencies)
• [Running Tests](#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).

```bash export FHIRSERVERBASEURL="" export FHIRSERVERCLIENTID="" export FHIRSERVERCLIENTSECRET="" export FHIRSERVER_SCOPES=""

export FHIRMCPHOST="localhost" export FHIRMCPPORT="8000" ```

1. Install the PyPI package and run the server

``bash uvx fhir-mcp-server ``

Installing from Source

1. Clone the repository:

``bash git clone cd ``

1. Create a virtual environment and install dependencies:

``bash uv venv source .venv/bin/activate uv pip sync requirements.txt ` Or with pip: `bash python -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``

1. Configure Environment Variables:

Copy the example file and customize if needed: ``bash cp .env.example .env ``

1. Run the server:

``bash 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:

``bash docker build -t fhir-mcp-server . ``

• Pull from GitHub Container Registry:

``bash docker pull wso2/fhir-mcp-server:latest ``

1. Configure Environment Variables

Copy the example environment file and edit as needed:

``bash 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](#configuration) section for details on available environment variables.

1. Run the Container

``bash 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.

1. Run the Stack:

``bash 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.

1. Access the Services:

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

1. 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](#configuration) section for full options.

Integration with MCP Clients

The FHIR MCP Server is designed for seamless integration with various MCP clients.

VS Code

[](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=fhir&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A8000%2Fmcp%2F%22%7D)

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 HTTPSTDIOSSE

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

• 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/claudedesktopconfig.json
• Windows: %APPDATA%\Claude\claudedesktopconfig.json
• Open the claudedesktopconfig.json file in any text editor. Replace its contents with the following JSON block to register the MCP server:

Streamable HTTPSTDIOSSE

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

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

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

• 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

• --help
• Description: Displays a help message with available server options and exits.
• Usage: Automatically provided by the command-line interface.

Sample Usages:

uv run fhir-mcp-server --transport streamable-http --log-level DEBUG
uv run fhir-mcp-server --help

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, or 0.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_DISABLE_AUTHORIZATION: If set to True, disables authorization checks on the MCP server, allowing connections to publicly accessible FHIR servers.
• 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). Add fhirUser openid to enable retrieval of user context for the get_user tool. If these two scopes are not configured, the get_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"}).
• 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", "C

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wso2
• Source: wso2/fhir-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.