|
1 | | -# fhir-mcp-server |
2 | | -This server lets you interact with Fast Healthcare Interoperability Resources (FHIR) resources on a specified FHIR server. |
| 1 | +# Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR) |
| 2 | + |
| 3 | +[](https://github.com/wso2/fhir-mcp-server/blob/main/LICENSE) |
| 4 | +[](https://stackoverflow.com/questions/tagged/wso2) |
| 5 | +[](https://discord.com/invite/wso2) |
| 6 | +[](https://twitter.com/intent/follow?screen_name=wso2) |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +The MCP Server for FHIR is a Python-based service that provides seamless, standardized access to FHIR data from any compatible FHIR server. 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. |
| 11 | + |
| 12 | +**Key features:** |
| 13 | +- **Flexible Integration:** Use the server from the command line, in Docker, or directly within tools like VS Code, Claude Desktop, and MCP Inspector. |
| 14 | +- **Natural Language FHIR Search:** Query for patients, allergies, immunizations, care plans, and more using simple prompts or programmatic requests. |
| 15 | +- **Configurable & Secure:** Easily connect to any FHIR server, with support for environment-based configuration and secure access tokens. |
| 16 | +- **Developer Friendly:** Quick setup with modern Python tooling (`uv`), clear documentation, and ready-to-use integration examples for rapid prototyping and deployment. |
| 17 | + |
| 18 | +Whether you are building healthcare applications, integrating with AI assistants, or exploring clinical datasets, the MCP server provides a robust foundation for accessing and working with FHIR data in a standardized, extensible way. |
| 19 | + |
| 20 | +## Prerequisites |
| 21 | +- Python 3.8+ |
| 22 | +- [uv](https://github.com/astral-sh/uv) (for dependency management) |
| 23 | +- An accessible FHIR server (defaults to the public HAPI FHIR test server) |
| 24 | + |
| 25 | +## Setup |
| 26 | + |
| 27 | +1. **Clone the repository:** |
| 28 | + ```bash |
| 29 | + git clone <repository_url> |
| 30 | + cd <repository_directory> |
| 31 | + ``` |
| 32 | +2. **Create a virtual environment and install dependencies:** |
| 33 | + ```bash |
| 34 | + uv venv |
| 35 | + source .venv/bin/activate |
| 36 | + uv pip sync requirements.txt |
| 37 | + ``` |
| 38 | + Or with pip: |
| 39 | + ```bash |
| 40 | + python -m venv .venv |
| 41 | + source .venv/bin/activate |
| 42 | + pip install -r requirements.txt |
| 43 | + ``` |
| 44 | +3. **Configure Environment Variables:** |
| 45 | + Copy the example file and customize if needed: |
| 46 | + ```bash |
| 47 | + cp .env.example .env |
| 48 | + ``` |
| 49 | + |
| 50 | +## Usage |
| 51 | + |
| 52 | +Run the server: |
| 53 | +```bash |
| 54 | +uv run fhir-mcp-server |
| 55 | +``` |
| 56 | + |
| 57 | +You can also run the server directly from the PyPI package (without cloning the repository) using: |
| 58 | + |
| 59 | +```bash |
| 60 | +uvx fhir-mcp-server |
| 61 | +``` |
| 62 | + |
| 63 | +## VS Code Integration |
| 64 | +Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON). |
| 65 | + |
| 66 | +<table> |
| 67 | +<tr><th>Streamable HTTP</th><th>stdio</th></tr> |
| 68 | +<tr valign=top> |
| 69 | +<td> |
| 70 | + |
| 71 | +```json |
| 72 | +"mcp": { |
| 73 | + "servers": { |
| 74 | + "fhir": { |
| 75 | + "command": "npx", |
| 76 | + "args": [ |
| 77 | + "-y", |
| 78 | + "mcp-remote", |
| 79 | + "http://localhost:8000/mcp" |
| 80 | + ] |
| 81 | + } |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | +</td> |
| 86 | +<td> |
| 87 | + |
| 88 | +```json |
| 89 | +"mcp": { |
| 90 | + "servers": { |
| 91 | + "fhir": { |
| 92 | + "command": "uv", |
| 93 | + "args": [ |
| 94 | + "--directory", |
| 95 | + "/path/to/fhir-mcp-server", |
| 96 | + "run", |
| 97 | + "fhir-mcp-server", |
| 98 | + "--transport", |
| 99 | + "stdio" |
| 100 | + ], |
| 101 | + "env": { |
| 102 | + "HEALTHCARE_MCP_FHIR__ACCESS_TOKEN": "Your FHIR Access Token" |
| 103 | + } |
| 104 | + } |
| 105 | + } |
| 106 | +} |
| 107 | +``` |
| 108 | +</td> |
| 109 | +</tr> |
| 110 | +</table> |
| 111 | + |
| 112 | +## Claude Desktop Integration |
| 113 | +Add the following JSON block to your Claude Desktop settings to connect to your local MCP server. |
| 114 | + - Launch the Claude Desktop app, click on the Claude menu in the top bar, and select "Settings…". |
| 115 | + - 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: |
| 116 | + - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json |
| 117 | + - Windows: %APPDATA%\Claude\claude_desktop_config.json |
| 118 | + - Open the claude_desktop_config.json file in any text editor. Replace its contents with the following JSON block to register the MCP server: |
| 119 | + |
| 120 | +<table> |
| 121 | +<tr><th>Streamable HTTP</th><th>stdio</th></tr> |
| 122 | +<tr valign=top> |
| 123 | +<td> |
| 124 | + |
| 125 | +```json |
| 126 | +{ |
| 127 | + "mcpServers": { |
| 128 | + "fhir": { |
| 129 | + "command": "npx", |
| 130 | + "args": [ |
| 131 | + "-y", |
| 132 | + "mcp-remote", |
| 133 | + "http://localhost:8000/mcp" |
| 134 | + ] |
| 135 | + } |
| 136 | + } |
| 137 | +} |
| 138 | +``` |
| 139 | +</td> |
| 140 | +<td> |
| 141 | + |
| 142 | +```json |
| 143 | +{ |
| 144 | + "mcpServers": { |
| 145 | + "fhir": { |
| 146 | + "command": "uv", |
| 147 | + "args": [ |
| 148 | + "--directory", |
| 149 | + "/path/to/fhir-mcp-server", |
| 150 | + "run", |
| 151 | + "fhir-mcp-server", |
| 152 | + "--transport", |
| 153 | + "stdio" |
| 154 | + ], |
| 155 | + "env": { |
| 156 | + "HEALTHCARE_MCP_FHIR__ACCESS_TOKEN": "Your FHIR Access Token" |
| 157 | + } |
| 158 | + } |
| 159 | + } |
| 160 | +} |
| 161 | +``` |
| 162 | +</td> |
| 163 | +</tr> |
| 164 | +</table> |
| 165 | + |
| 166 | +## MCP Inspector Integration |
| 167 | +Follow these steps to get the MCP Inspector up and running: |
| 168 | + |
| 169 | +- Open a terminal and run the following command: |
| 170 | + |
| 171 | + `npx -y @modelcontextprotocol/inspector` |
| 172 | + |
| 173 | +- In the MCP Inspector interface: |
| 174 | +<table> |
| 175 | +<tr><th>Streamable HTTP</th><th>stdio</th></tr> |
| 176 | +<tr valign=top> |
| 177 | +<td> |
| 178 | + |
| 179 | +- Transport Type: `Streamable HTTP` |
| 180 | +- URL: `http://localhost:8000/mcp` |
| 181 | +</td> |
| 182 | +<td> |
| 183 | + |
| 184 | +- Transport Type: `STDIO` |
| 185 | +- Command: `uv` |
| 186 | +- Arguments: `--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio` |
| 187 | +</td> |
| 188 | +</tr> |
| 189 | +</table> |
| 190 | + |
| 191 | +Make sure your MCP server is already running and listening on the above endpoint. |
| 192 | + |
| 193 | +Once connected, MCP Inspector will allow you to visualize tool invocations, inspect request/response payloads, and debug your tool implementations easily. |
| 194 | + |
| 195 | +## Example Prompts |
| 196 | +- Get allergy history for patient 53373 |
| 197 | +- Fetch the immunization records for patient ID 53373 |
| 198 | +- List all active care plans for patient 22 |
| 199 | +- Provide a consolidated report for patient 53373 that includes their complete allergy history as well as all available immunization records, organized by date and highlighting any critical alerts |
| 200 | +- Retrieve all active care plans for patient ID 22 and present them in a markdown table showing each plan’s ID, title, status, intent, and start date |
0 commit comments