Fhir MCP Server

1# Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs
2 
3[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/wso2/fhir-mcp-server/blob/main/LICENSE)
4[![Get Support on Stack Overflow](https://img.shields.io/badge/stackoverflow-wso2-orange)](https://stackoverflow.com/questions/tagged/wso2)
5[![Join the community on Discord](https://img.shields.io/badge/Join%20us%20on-Discord-%23e01563.svg)](https://discord.com/invite/wso2)
6[![X](https://img.shields.io/twitter/follow/wso2.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=wso2)
7 
8## Table of Contents
9- [Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) APIs](#model-context-protocol-mcp-server-for-fast-healthcare-interoperability-resources-fhir-apis)
10  - [Table of Contents](#table-of-contents)
11  - [Overview](#overview)
12  - [Demo](#demo)
13    - [Demo with HAPI FHIR server](#demo-with-hapi-fhir-server)
14    - [Demo with EPIC Sandbox](#demo-with-epic-sandbox)
15  - [Core Features](#core-features)
16  - [Prerequisites](#prerequisites)
17  - [Installation](#installation)
18    - [Installing using PyPI Package](#installing-using-pypi-package)
19    - [Installing from Source](#installing-from-source)
20    - [Installing using Docker](#installing-using-docker)
21        - [Running the MCP Server with Docker](#running-the-mcp-server-with-docker)
22        - [Using Docker Compose with HAPI FHIR Server](#using-docker-compose-with-hapi-fhir-server)
23  - [Integration with MCP Clients](#integration-with-mcp-clients)
24    - [VS Code](#vs-code)
25    - [Claude Desktop](#claude-desktop)
26    - [MCP Inspector](#mcp-inspector)
27  - [Configuration](#configuration)
28    - [CLI Options](#cli-options)
29    - [Environment Variables](#environment-variables)
30  - [Tools](#tools)
31  - [Development \& Testing](#development--testing)
32    - [Installing Development Dependencies](#installing-development-dependencies)
33    - [Running Tests](#running-tests)
34 
35 
36## Overview
37 
38The 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.
39 
40## Demo
41 
42### Demo with HAPI FHIR server
43 
44This video showcases the MCP server's functionality when connected to a public [HAPI FHIR server](https://hapi.fhir.org/). This example showcases direct interaction with an open FHIR server that does not require an authorization flow.
45 
46https://github.com/user-attachments/assets/cc6ac87e-8329-4da4-a090-2d76564a3abf
47 
48### Demo with EPIC Sandbox
49 
50This video showcases the MCP server's capabilities within the [Epic EHR ecosystem](https://open.epic.com/). It demonstrates the complete OAuth 2.0 Authorization Code Grant flow.
51 
52https://github.com/user-attachments/assets/96b433f1-3e53-4564-8466-65ab48d521de
53 
54## Core Features
55 
56- **MCP-compatible transport**: Serves FHIR via stdio, SSE, or streamable HTTP
57 
58- **SMART-on-FHIR based authentication support**: Securely authenticate with FHIR servers and clients
59 
60- **Tool integration**: Integratable with any MCP client such as VS Code, Claude Desktop, and MCP Inspector
61 
62## Prerequisites
63 
64- Python 3.8+
65- [uv](https://github.com/astral-sh/uv) (for dependency management)
66- An accessible FHIR API server.
67 
68## Installation
69 
70You can use the FHIR MCP Server by installing our Python package, or by cloning this repository.
71 
72### Installing using PyPI Package
73 
741. **Configure Environment Variables:**
75    
76    To run the server, you must set `FHIR_SERVER_BASE_URL`.
77 
78    * **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.
79    * **To disable authorization:** Set `FHIR_SERVER_DISABLE_AUTHORIZATION` to `True`.
80 
81    By default, the MCP server runs on **[http://localhost:8000](http://localhost:8000)**, and you can customize the host and port using `FHIR_MCP_HOST` and `FHIR_MCP_PORT`.
82 
83 
84    You can set these by exporting them as environment variables like below or by creating a `.env` file (referencing `.env.example`).
85 
86    ```bash 
87    export FHIR_SERVER_BASE_URL=""
88    export FHIR_SERVER_CLIENT_ID=""
89    export FHIR_SERVER_CLIENT_SECRET=""
90    export FHIR_SERVER_SCOPES=""
91 
92    export FHIR_MCP_HOST="localhost"
93    export FHIR_MCP_PORT="8000"
94    ```
95 
962. **Install the PyPI package and run the server**
97 
98    ```bash
99    uvx fhir-mcp-server
100    ```
101 
102### Installing from Source
103 
1041. **Clone the repository:**
105    ```bash
106    git clone <repository_url>
107    cd <repository_directory>
108    ```
109 
1102. **Create a virtual environment and install dependencies:**
111    ```bash
112    uv venv
113    source .venv/bin/activate
114    uv pip sync requirements.txt
115    ```
116    Or with pip:
117    ```bash
118    python -m venv .venv
119    source .venv/bin/activate
120    pip install -r requirements.txt
121    ```
122 
1233. **Configure Environment Variables:**
124    Copy the example file and customize if needed:
125    ```bash
126    cp .env.example .env
127    ```
128 
1294. **Run the server:**
130    ```bash
131    uv run fhir-mcp-server
132    ```
133 
134### Installing using Docker
135 
136#### Running the MCP Server with Docker
137 
138You can run the MCP server using Docker for a consistent, isolated environment. 
139 
140>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.
141 
1421. Build the Docker Image or pull the docker image from the container registry:
143 
144    * Build from source:
145        ```bash
146        docker build -t fhir-mcp-server .
147        ```
148    * Pull from GitHub Container Registry:
149        ```bash
150        docker pull wso2/fhir-mcp-server:latest
151        ```
152 
1532. Configure Environment Variables
154 
155    Copy the example environment file and edit as needed:
156 
157    ```bash
158    cp .env.example .env
159    # Edit .env to set your FHIR server, client credentials, etc.
160    ```
161 
162    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.
163 
1643. Run the Container
165 
166    ```bash
167    docker run --env-file .env -p 8000:8000 fhir-mcp-server
168    ```
169 
170    This will start the server and expose it on port 8000. Adjust the port mapping as needed.
171 
172#### Using Docker Compose with HAPI FHIR Server
173 
174For 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.
175 
1761. **Prerequisites:**
177   - Docker and Docker Compose installed.
178 
1792. **Run the Stack:**
180 
181   ```bash
182   docker-compose up -d
183   ```
184 
185   This command will:
186   - Start a PostgreSQL database container.
187   - Launch the HAPI FHIR server (connected to PostgreSQL) listening on http://localhost:8080.
188   - 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.
189 
1903. **Access the Services:**
191   - FHIR MCP Server: http://localhost:8000
192   - HAPI FHIR Server: http://localhost:8080
193   - To stop run `docker-compose down`.
194 
1954. **Configure Additional Environment Variables:**
196 
197   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.
198 
199## Integration with MCP Clients
200 
201The FHIR MCP Server is designed for seamless integration with various MCP clients.
202 
203### VS Code
204 
205[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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)
206[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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)
207 
208Add 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`.
209 
210<table>
211<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>
212<tr valign=top>
213<td>
214 
215```json
216"servers": {
217    "fhir": {
218        "type": "http",
219        "url": "http://localhost:8000/mcp",
220    }
221}
222```
223</td>
224 
225<td>
226 
227```json
228"servers": {
229    "fhir": {
230        "command": "uv",
231        "args": [
232            "--directory",
233            "/path/to/fhir-mcp-server",
234            "run",
235            "fhir-mcp-server",
236            "--transport",
237            "stdio"
238        ],
239        "env": {
240            "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
241        }
242    }
243}
244```
245</td>
246 
247<td>
248 
249```json
250"servers": {
251    "fhir": {
252        "type": "sse",
253        "url": "http://localhost:8000/sse",
254    }
255}
256```
257</td>
258</tr>
259</table>
260 
261### Claude Desktop
262Add the following JSON block to your Claude Desktop settings to connect to your local MCP server. 
263 - Launch the Claude Desktop app, click on the Claude menu in the top bar, and select "Settings…".
264 - 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:
265    - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
266    - Windows: %APPDATA%\Claude\claude_desktop_config.json
267 - Open the claude_desktop_config.json file in any text editor. Replace its contents with the following JSON block to register the MCP server:
268 
269<table>
270<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>
271<tr valign=top>
272<td>
273 
274```json
275{
276    "mcpServers": {
277        "fhir": {
278            "command": "npx",
279            "args": [
280                "-y",
281                "mcp-remote",
282                "http://localhost:8000/mcp"
283            ]
284        }
285    }
286}
287```
288</td>
289<td>
290 
291```json
292{
293    "mcpServers": {
294        "fhir": {
295            "command": "uv",
296            "args": [
297                "--directory",
298                "/path/to/fhir-mcp-server",
299                "run",
300                "fhir-mcp-server",
301                "--transport",
302                "stdio"
303            ],
304            "env": {
305                "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
306            }
307        }
308    }
309}
310```
311</td>
312 
313<td>
314 
315```json
316{
317    "mcpServers": {
318        "fhir": {
319            "command": "npx",
320            "args": [
321                "-y",
322                "mcp-remote",
323                "http://localhost:8000/sse"
324            ]
325        }
326    }
327}
328```
329</td>
330</tr>
331</table>
332 
333### MCP Inspector
334Follow these steps to get the MCP Inspector up and running:
335 
336- Open a terminal and run the following command:
337    
338    `npx -y @modelcontextprotocol/inspector`
339 
340- In the MCP Inspector interface:
341<table>
342<tr><th>Streamable HTTP</th><th>STDIO</th><th>SSE</th></tr>
343<tr valign=top>
344<td>
345 
346- Transport Type: `Streamable HTTP`
347- URL: `http://localhost:8000/mcp`
348</td>
349 
350<td>
351 
352- Transport Type: `STDIO`
353- Command: `uv`
354- Arguments: `--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio`
355</td>
356 
357<td>
358 
359- Transport Type: `SSE`
360- URL: `http://localhost:8000/sse`
361</td>
362</tr>
363</table>
364 
365Make sure your MCP server is already running and listening on the above endpoint.
366 
367Once connected, MCP Inspector will allow you to visualize tool invocations, inspect request/response payloads, and debug your tool implementations easily.
368 
369## Configuration
370 
371### CLI Options
372 
373You can customize the behavior of the MCP server using the following command-line flags:
374 
375- **--transport**
376    - Description: Specifies the transport protocol used by the MCP server to communicate with clients.
377    - Accepted values: stdio, sse, streamable-http
378    - Default: streamable-http
379 
380- **--log-level**
381    - Description: Sets the logging verbosity level for the server.
382    - Accepted values: DEBUG, INFO, WARN, ERROR (case-insensitive)
383    - Default: INFO
384 
385- **--help**
386    - Description: Displays a help message with available server options and exits.
387    - Usage: Automatically provided by the command-line interface.
388 
389Sample Usages:
390 
391```shell
392uv run fhir-mcp-server --transport streamable-http --log-level DEBUG
393uv run fhir-mcp-server --help
394```
395 
396### Environment Variables
397 
398**MCP Server Configurations:**
399- `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).
400- `FHIR_MCP_PORT`: The port on which the MCP server will listen for incoming client requests (e.g., `8000`).
401- `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.
402- `FHIR_MCP_REQUEST_TIMEOUT`: Timeout duration in seconds for requests from the MCP server to the FHIR server (default: `30`).
403 
404**MCP Server OAuth2 with FHIR server Configuration (MCP Client ↔ MCP Server):**
405These variables configure the MCP client's secure connection to the MCP server, using the OAuth2 authorization code grant flow with a FHIR server.
406 
407- `FHIR_SERVER_CLIENT_ID`: The OAuth2 client ID used to authorize MCP clients with the FHIR server.
408- `FHIR_SERVER_DISABLE_AUTHORIZATION`: If set to `True`, disables authorization checks on the MCP server, allowing connections to publicly accessible FHIR servers.
409- `FHIR_SERVER_CLIENT_SECRET`: The client secret corresponding to the FHIR client ID. Used during token exchange.
410- `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.
411- `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.
412- `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.
413 
414## Tools
415 
416- `get_capabilities`: Retrieves metadata about a specified FHIR resource type, including its supported search parameters and custom operations.
417    - `type`: The FHIR resource type name (e.g., "Patient", "Observation", "Encounter")
418 
419- `search`: Executes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources.
420    - `type`: The FHIR resource type name (e.g., "MedicationRequest", "Condition", "Procedure").
421    - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"family":"Simpson","birthdate":"1956-05-12"}).
422 
423- `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.
424    - `type`: The FHIR resource type name (e.g., "DiagnosticReport", "AllergyIntolerance", "Immunization").
425    - `id`: The logical ID of a specific FHIR resource instance.
426    - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"device-name":"glucometer"}).
427    - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$everything").
428 
429- `create`: Executes a FHIR "create" interaction to persist a new resource of the specified type.
430    - `type`: The FHIR resource type name (e.g., "Device", "CarePlan", "Goal").
431    - `payload`: A JSON object representing the full FHIR resource body to be created.
432    - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"address-city":"Boston"}).
433    - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$evaluate").
434 
435- `update`: Performs a FHIR "update" interaction by replacing an existing resource instance's content with the provided payload.
436    - `type`: The FHIR resource type name (e.g., "Location", "Organization", "Coverage").
437    - `id`: The logical ID of a specific FHIR resource instance.
438    - `payload`: The complete JSON representation of the FHIR resource, containing all required elements and any optional data.
439    - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"patient":"Patient/54321","relationship":"father"}).
440    - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$lastn").
441 
442- `delete`: Execute a FHIR "delete" interaction on a specific resource instance.
443    - `type`: The FHIR resource type name (e.g., "ServiceRequest", "Appointment", "HealthcareService").
444    - `id`: The logical ID of a specific FHIR resource instance.
445    - `searchParam`: A mapping of FHIR search parameter names to their desired values (e.g., {"category":"laboratory","issued:"2025-05-01"}).
446    - `operation`: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$expand").
447 
448- `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`.
449 
450## Development & Testing
451 
452### Installing Development Dependencies
453 
454To run tests and contribute to development, install the test dependencies:
455 
456**Using pip:**
457```bash
458# Install project in development mode with test dependencies
459pip install -e '.[test]'
460 
461# Or install from requirements file
462pip install -r requirements-dev.txt
463```
464 
465**Using uv:**
466```bash
467# Install development dependencies
468uv sync --dev
469```
470 
471### Running Tests
472 
473The project includes a comprehensive test suite covering all major functionality:
474 
475```bash
476# Simple test runner
477python run_tests.py
478 
479# Or direct pytest usage
480PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server
481```
482**Using pytest:**
483```bash
484pytest tests/
485```
486This will discover and run all tests in the `tests/` directory.
487 
488 
489**Test Features:**
490- **100+ tests** with comprehensive coverage
491- **Full async/await support** using pytest-asyncio
492- **Complete mocking** of HTTP requests and external dependencies
493- **Coverage reporting** with terminal and HTML output
494- **Fast execution** with no real network calls
495 
496The test suite includes:
497- **Unit tests**: Core functionality testing
498- **Integration tests**: Component interaction validation
499- **Edge case coverage**: Error handling and validation scenarios
500- **Mocked OAuth flows**: Realistic authentication testing
501 
502Coverage reports are generated in `htmlcov/index.html` for detailed analysis.
503 
504<!-- mcp-name: io.github.wso2/fhir-mcp-server -->
505