Skip to content
Back to search

fhir-mcp-server

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wso2--fhir-mcp-server/badge.svg)](/listings/wso2--fhir-mcp-server)

HTML

<a href="/listings/wso2--fhir-mcp-server"><img src="/api/listings/wso2--fhir-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](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 FHIR_SERVER_BASE_URL="" export FHIR_SERVER_CLIENT_ID="" export FHIR_SERVER_CLIENT_SECRET="" export FHIR_SERVER_SCOPES=""

export FHIR_MCP_HOST="localhost" export FHIR_MCP_PORT="8000" ```

2. **Install the PyPI package and run the server**

```bash uvx fhir-mcp-server ```

Installing from Source

1. **Clone the repository:** ```bash git clone <repository_url> cd <repository_directory> ```

2. **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 ```

3. **Configure Environment Variables:** Copy the example file and customize if needed: ```bash cp .env.example .env ```

4. **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 ```

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

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

2. **Run the Stack:**

   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.

3. **Access the Services:** - FHIR MCP Server: http://localhost:8000 - HAPI FHIR Server: http://localhost:8080 - To stop run `docker-compose down`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 562 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.