Skip to content
Back to search

fhir-mcp-server

FHIR MCP Server for handling medical data standard.

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/the-momentum--fhir-mcp-server/badge.svg)](/listings/the-momentum--fhir-mcp-server)

HTML

<a href="/listings/the-momentum--fhir-mcp-server"><img src="/api/listings/the-momentum--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.

Follow these steps to set up FHIR MCP Server in your environment.

Prerequisites

- **Docker (recommended) or uv**: For dependency management

πŸ‘‰ [uv Installation Guide](https://docs.astral.sh/uv/getting-started/installation/) - **FHIR Server Account**: Access to FHIR API (e.g. Medplum) - **Pinecone API key** (required for document search): Enables vector-based search over processed documents. Without it, semantic retrieval features will be unavailable.

πŸ‘‰ [Create Pinecone Account](https://www.pinecone.io/) - **LOINC Account** (optional): Enables retrieval of the latest LOINC codes from the official API. Without it, the system relies on static or language model-inferred codes, which may be outdated or imprecise.

πŸ‘‰[Create LOINC Account](https://loinc.org/join/)

Installation & Setup

1. **Clone the repository**:

   git clone https://github.com/the-momentum/fhir-mcp-server
   cd fhir-mcp-server

2. **Set up environment variables**:

   cp config/.env.example config/.env

Edit the `config/.env` file with your credentials and configuration. See [Environment Variables](#-Environment-Variables)

3. **Install Dependencies**

For Docker-based execution run:

   make build

For uv-based execution run:

   make uv

4. **Update the MCP Client configuration**

e.g. Claude Desktop -> edit ```claude_desktop_config.json```

- **Docker**

   {
      "mcpServers": {
         "docker-mcp-server": {
            "command": "docker",
            "args": [
               "run",
               "-i",
               "--rm",
               "--init",
               "--name",
               "fhir-mcp-server",
               "--mount", // optional - volume for reload
               "type=bind,source=<your-project-path>/app,target=/root_project/app", // optional - volume for reload
               "--mount",
               "type=bind,source=<your-project-path>/config/.env,target=/root_project/config/.env",
               "-e", "TRANSPORT_MODE=stdio", // Set transport mode: stdio, http, or https
               "mcp-server:latest"
            ]
         }
      }
   }

Make sure to replace ```<your-project-path>``` with the actual path to your installation

- **uv**

Firstly, get uv path from terminal:

- Windows: ``` (Get-Command uv).Path ```

- MacOS/Linux: ``` which uv ``` Then, update config file:

   {
      "mcpServers": {
         "uv-mcp-server": {
            "command": "uv",
            "args": [
               "run",
               "--frozen",
               "--directory",
               "<your-project-path>",
               "start"
            ],
            "env": {
            "PATH": "<uv-bin-folder-path>"
            }
         }
      }
   }

Make sure to replace <uv-bin-folder-path> with the actual uv path (to bin folder)

5. **Restart MCP Client**

After completing all of the above steps, restart the MCP Client to apply the changes. In some cases, you may need to terminate all related processes using Task Manager or your system's process manager. This ensures that:

- The updated configuration is properly loaded - Environment variables are correctly applied - The FHIR MCP client initializes with the correct settings

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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 Β· 371 lines

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

  1. <a name="readme-top"></a>
  2. <div align="center">
  3. <img src="https://cdn.prod.website-files.com/66a1237564b8afdc9767dd3d/66df7b326efdddf8c1af9dbb_Momentum%20Logo.svg" height="80">
  4. <h1>FHIR MCP Server</h1>
  5. <p><strong>Model Context Protocol (MCP) Server for Fast Healthcare Interoperability Resources (FHIR)</strong></p>
  6. [![Contact us](https://img.shields.io/badge/Contact%20us-AFF476.svg?style=for-the-badge&logo=mail&logoColor=black)](mailto:hello@themomentum.ai?subject=FHIR%20MCP%20Server%20Inquiry)
  7. [![Visit Momentum](https://img.shields.io/badge/Visit%20Momentum-1f6ff9.svg?style=for-the-badge&logo=safari&logoColor=white)](https://themomentum.ai)
  8. [![MIT License](https://img.shields.io/badge/License-MIT-636f5a.svg?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](LICENSE)
  9. </div>
  10. ## πŸ“‹ Table of Contents
  11. - [πŸ” About](#-about-the-project)
  12. - [πŸ’‘ Demo](#-demo)
  13. - [πŸš€ Getting Started](#-getting-started)
  14. - [πŸ“ Usage](#-usage)
  15. - [πŸ”§ Configuration](#-configuration)
  16. - [🐳 Docker Setup](#-docker-setup)
  17. - [πŸ› οΈ MCP Tools](#️-mcp-tools)
  18. - [πŸ—ΊοΈ Roadmap](#️-roadmap)
  19. - [πŸ‘₯ Contributors](#-contributors)
  20. - [πŸ“„ License](#-license)
  21. ## πŸ” About The Project
  22. **FHIR MCP Server** implements a complete Model Context Protocol (MCP) server, designed to facilitate seamless interaction between LLM-based agents and a FHIR-compliant backend. It provides a standardized interface that enables full CRUD operations on FHIR resources through a comprehensive suite of tools - accessible from MCP-compatible clients such as Claude Desktop, allowing users to query and manipulate clinical data using natural-language prompts.
  23. ### ✨ Key Features
  24. - **πŸš€ FastMCP Framework**: Built on FastMCP for high-performance MCP server capabilities
  25. - **πŸ₯ FHIR Resource Management**: Full CRUD operations for all major FHIR resources
  26. - **πŸ“„ Intelligent Document Processing**: AI-powered document ingestion and chunking for multiple formats including TXT, CSV, JSON, and PDF
  27. - **πŸ” Semantic Search**: Advanced document search using vector embeddings (via Pinecone)
  28. - **🧠 RAG-Ready**: Retrieval-Augmented Generation pipeline with context-aware document queries
  29. - **πŸ” Secure Authentication**: OAuth2 token management for FHIR API integration
  30. - **πŸ“Š LOINC Integration**: Standardized medical terminology lookup and validation
  31. - **🐳 Container Ready**: Docker support for easy deployment and scaling
  32. - **πŸ”§ Configurable**: Extensive ```.env```-based configuration options
  33. ### πŸ—οΈ Architecture
  34. The server is built with a modular architecture:
  35. - **MCP Tools**: Dedicated tools for selected FHIR resource types, with others handled by a generic tool
  36. - **Fhir Server Client**: Handles FHIR API communication and authentication (OAuth2 and more planned)
  37. - **RAG Services**: Embedding-based document processing and semantic retrieval
  38. - **Vector Store**: Pinecone integration for similarity-based search
  39. - **LOINC Client**: Integration with LOINC API for terminology resolution and validation
  40. <p align="right">(<a href="#readme-top">back to top</a>)</p>
  41. ## πŸ’‘ Demo
  42. This demo shows how Claude uses the `fhir-mcp-server` to communicate with a FHIR server (in this case Medplum) to answer questions. You will see, among other things:
  43. - utilization of the `request_patient_resource` tool which retrieves basic patient information
  44. - utilization of the `request_condition_resource` tool to answer the question whether any of the previously diagnosed diseases may cause symptoms that the patient is currently complaining about
  45. - utilization of the `request_medication_resource`, `request_encounter_resource`, `request_generic_resource` tools to answer the question whether the patient has already received any treatment for hypertension
  46. You can observe how Claude automatically selects the tools worth using to answer the question based on the user's query.
  47. https://github.com/user-attachments/assets/3a3a8ed3-f881-447d-af03-5f24432a2cdd
  48. <details>
  49. <summary>Lab History Analysis</summary>
  50. Here you can observe how Claude first uses the tool searching for LOINC codes for the lipid panel specific codes, but not finding any related observations in FHIR server, it repeats the search for individual biomarkers that make up such a panel.
  51. https://github.com/user-attachments/assets/2fb39801-d5d6-4461-bedd-9f58ab4d52ec
  52. </details>
  53. <details>
  54. <summary>FHIR Synthetic Data Generator</summary>
  55. Developers working with FHIR often need to generate specific test data to validate FHIR server functionality, such as search capabilities and data relationships. While you can use Synthea to generate synthetic data and then manually import the resulting bundles to your server, fhir-mcp-server streamlines this process by allowing you to generate and deploy test data directly through Claude.
  56. This eliminates the typical workflow of running [synthea](https://github.com/synthetichealth/synthea) separately, downloading bundles, and manually importing them to your FHIR server. Instead, you can create targeted test scenarios, generate appropriate synthetic data, and populate your server all within Claude's interface.
  57. https://github.com/user-attachments/assets/d87da1d8-6401-4a9e-a6f0-50ba23396e12
  58. **Note:** fhir-mcp-server was not designed with this use case in mind, so as you'll see in the demo, it doesn't work perfectly - what can be observed, however, is how well the LLM handles using trial and error to correct any wrong choices.
  59. </details>
  60. ## πŸš€ Getting Started
  61. Follow these steps to set up FHIR MCP Server in your environment.
  62. ### Prerequisites
  63. - **Docker (recommended) or uv**: For dependency management
  64. πŸ‘‰ [uv Installation Guide](https://docs.astral.sh/uv/getting-started/installation/)
  65. - **FHIR Server Account**: Access to FHIR API (e.g. Medplum)
  66. - **Pinecone API key** (required for document search): Enables vector-based search over processed documents. Without it, semantic retrieval features will be unavailable.
  67. πŸ‘‰ [Create Pinecone Account](https://www.pinecone.io/)
  68. - **LOINC Account** (optional): Enables retrieval of the latest LOINC codes from the official API. Without it, the system relies on static or language model-inferred codes, which may be outdated or imprecise.
  69. πŸ‘‰[Create LOINC Account](https://loinc.org/join/)
  70. ### Installation & Setup
  71. 1. **Clone the repository**:
  72. ```sh
  73. git clone https://github.com/the-momentum/fhir-mcp-server
  74. cd fhir-mcp-server
  75. ```
  76. 2. **Set up environment variables**:
  77. ```sh
  78. cp config/.env.example config/.env
  79. ```
  80. Edit the `config/.env` file with your credentials and configuration. See [Environment Variables](#-Environment-Variables)
  81. 3. **Install Dependencies**
  82. For Docker-based execution run:
  83. ```sh
  84. make build
  85. ```
  86. For uv-based execution run:
  87. ```sh
  88. make uv
  89. ```
  90. 4. **Update the MCP Client configuration**
  91. e.g. Claude Desktop -> edit ```claude_desktop_config.json```
  92. - **Docker**
  93. ```json
  94. {
  95. "mcpServers": {
  96. "docker-mcp-server": {
  97. "command": "docker",
  98. "args": [
  99. "run",
  100. "-i",
  101. "--rm",
  102. "--init",
  103. "--name",
  104. "fhir-mcp-server",
  105. "--mount", // optional - volume for reload
  106. "type=bind,source=<your-project-path>/app,target=/root_project/app", // optional - volume for reload
  107. "--mount",
  108. "type=bind,source=<your-project-path>/config/.env,target=/root_project/config/.env",
  109. "-e", "TRANSPORT_MODE=stdio", // Set transport mode: stdio, http, or https
  110. "mcp-server:latest"
  111. ]
  112. }
  113. }
  114. }
  115. ```
  116. Make sure to replace ```<your-project-path>``` with the actual path to your installation
  117. - **uv**
  118. Firstly, get uv path from terminal:
  119. - Windows:
  120. ```
  121. (Get-Command uv).Path
  122. ```
  123. - MacOS/Linux:
  124. ```
  125. which uv
  126. ```
  127. Then, update config file:
  128. ```json
  129. {
  130. "mcpServers": {
  131. "uv-mcp-server": {
  132. "command": "uv",
  133. "args": [
  134. "run",
  135. "--frozen",
  136. "--directory",
  137. "<your-project-path>",
  138. "start"
  139. ],
  140. "env": {
  141. "PATH": "<uv-bin-folder-path>"
  142. }
  143. }
  144. }
  145. }
  146. ```
  147. Make sure to replace <uv-bin-folder-path> with the actual uv path (to bin folder)
  148. 5. **Restart MCP Client**
  149. After completing all of the above steps, restart the MCP Client to apply the changes. In some cases, you may need to terminate all related processes using Task Manager or your system's process manager. This ensures that:
  150. - The updated configuration is properly loaded
  151. - Environment variables are correctly applied
  152. - The FHIR MCP client initializes with the correct settings
  153. <p align="right">(<a href="#readme-top">back to top</a>)</p>
  154. ## πŸ”§ Configuration
  155. ### πŸ” Security & Encryption
  156. The FHIR MCP Server includes built-in encryption infrastructure to protect sensitive configuration values. Sensitive fields like API keys and passwords are automatically encrypted and decrypted at runtime.
  157. You are allowed to store passwords as a plain text, but if you want to have them encrypted, follow the instruction below.
  158. #### Setting Up Encryption
  159. <details>
  160. <summary>Automated Setup (Recommended)</summary>
  161. For most users, use the automated setup script:
  162. ```bash
  163. # uv method
  164. uv run scripts/cryptography/setup_encryption.py
  165. # docker method
  166. docker exec fhir-mcp-server uv run scripts/cryptography/setup_encryption.py
  167. ```
  168. This script will:
  169. 1. Check for `MASTER_KEY` in `config/.env` and generate one if needed
  170. 2. Automatically encrypt all sensitive values (`LOINC_PASSWORD`, `FHIR_SERVER_CLIENT_SECRET`, `PINECONE_API_KEY`)
  171. 3. Update your `.env` file with encrypted values
  172. 4. Skip empty variables and already encrypted values
  173. </details>
  174. <details>
  175. <summary>Manual Setup</summary>
  176. 1. **Generate a Master Key**:
  177. ```bash
  178. # uv method
  179. uv run scripts/cryptography/generate_master_key.py
  180. # docker method
  181. docker exec fhir-mcp-server uv run scripts/cryptography/generate_master_key.py
  182. ```
  183. Put that key as a MASTER_KEY environment variable in .env.
  184. 2. **Encrypt Sensitive Values**:
  185. ```bash
  186. # uv method
  187. uv run scripts/cryptography/encrypt_setting.py "your_secret_value"
  188. # docker method
  189. docker exec fhir-mcp-server uv run scripts/cryptography/encrypt_setting.py "your_secret_value"
  190. ```
  191. 3. **Decrypt Values** (for verification):
  192. ```bash
  193. # uv method
  194. uv run scripts/cryptography/decrypt_setting.py "encrypted_value"
  195. # docker method
  196. docker exec fhir-mcp-server uv run scripts/cryptography/decrypt_setting.py "encrypted_value"
  197. ```
  198. </details>
  199. #### Encrypted Configuration Fields
  200. The following fields are automatically encrypted when using `EncryptedField`:
  201. - `FHIR_SERVER_CLIENT_SECRET` - OAuth2 client secret for FHIR server
  202. - `LOINC_PASSWORD` - LOINC account password
  203. - `PINECONE_API_KEY` - Pinecone API key for vector search
  204. #### Environment Variables
  205. | Variable | Description | Example Value | Encryption |
  206. |----------|-------------|---------------|------------|
  207. | MASTER_KEY | Master encryption key | `gAAAAABl...` | Required |
  208. | FHIR_SERVER_HOST | FHIR API host URL | `https://api.medplum.com` | No |
  209. | FHIR_BASE_URL | FHIR base path | `/fhir/R4` | No |
  210. | FHIR_SERVER_CLIENT_ID | OAuth2 client ID for FHIR | `019720e7...` | No |
  211. | FHIR_SERVER_CLIENT_SECRET | OAuth2 client secret for FHIR | `gAAAAABl...` | **Yes** |
  212. | LOINC_ENDPOINT | LOINC API search endpoint | `https://loinc.regenstrief.org/searchapi/loincs` | No |
  213. | LOINC_USERNAME | LOINC account username | `loinc-user` | No |
  214. | LOINC_PASSWORD | LOINC account password | `gAAAAABl...` | **Yes** |
  215. | PINECONE_API_KEY | Pinecone API key | `gAAAAABl...` | **Yes** |
  216. | EMBEDDING_MODEL | Hugging Face embedding model name | `NeuML/pubmedbert-base-embeddings` | No |
  217. <p align="right">(<a href="#readme-top">back to top</a>)</p>
  218. ## πŸ› οΈ MCP Tools
  219. The FHIR MCP Server provides a comprehensive set of tools for interacting with FHIR resources and document management:
  220. ### FHIR Resource Tools
  221. | Tool | Resource Type | Description |
  222. |------|---------------|-------------|
  223. | `request_patient_resource` | Patient | Manage patient demographic and administrative information |
  224. | `request_observation_resource` | Observation | Handle clinical measurements and assessments |
  225. | `request_condition_resource` | Condition | Manage patient problems and diagnoses |
  226. | `request_medication_resource` | Medication | Handle medication information and orders |
  227. | `request_immunization_resource` | Immunization | Manage vaccination records |
  228. | `request_encounter_resource` | Encounter | Handle patient visits and interactions |
  229. | `request_allergy_intolerance_resource` | AllergyIntolerance | Manage patient allergy information |
  230. | `request_family_member_history_resource` | FamilyMemberHistory | Handle family health history |
  231. | `request_generic_resource` | Any FHIR Resource | Operate on any FHIR resource not covered by specific tools |
  232. ### Document Management Tools
  233. | Tool | Description |
  234. |------|-------------|
  235. | `request_document_reference_resource` | Manage FHIR DocumentReference resources |
  236. | `add_document_to_pinecone` | Ingests documents into the vector database for semantic search |
  237. | `search_pinecone` | Performs semantic search across indexed documents using vector embeddings |
  238. ### LOINC Terminology Tools
  239. | Tool | Description |
  240. |------|-------------|
  241. | `get_loinc_codes` | Retrieves standardized LOINC codes for medical observations and laboratory tests |
  242. ### Tool Features
  243. - **Full Resource Management**: All FHIR resource tools support Create, Read, Update, and Delete operations
  244. - **Data Validation**: Tools enforce FHIR resource validation and prevent data corruption
  245. - **Error Handling**: Comprehensive error responses with detailed failure information
  246. - **Security**: OAuth2 authentication and proper access control for all operations
  247. - **Semantic Search**: AI-powered document search using vector embeddings
  248. - **Multi-format Support**: Document ingestion supports TXT, PDF, CSV, and JSON formats
  249. <p align="right">(<a href="#readme-top">back to top</a>)</p>
  250. ## πŸ—ΊοΈ Roadmap
  251. We're continuously enhancing FHIR MCP Server with new capabilities. Here's what's on the horizon:
  252. - [ ] **Extended Authentication Options**: In addition to OAuth2 (already supported), we plan to add support for other authentication methods for connecting to FHIR servers
  253. - [ ] **Expanded File Format Support for RAG**: Extend document ingestion capabilities to support additional formats
  254. - [ ] **Table-Aware Document Chunking**: Improve the document chunking pipeline by detecting tables in documents and treating them as separate, atomic chunks.
  255. - [ ] **OCR Support for Scanned Documents**: Implement Optical Character Recognition capabilities to enable extraction of text from scanned PDFs and image files before chunking and indexing
  256. Have a suggestion? We'd love to hear from you! Contact us or contribute directly.
  257. ## πŸ‘₯ Contributors
  258. <a href="https://github.com/the-momentum/fhir-mcp-server/graphs/contributors">
  259. <img src="https://contrib.rocks/image?repo=the-momentum/fhir-mcp-server" />
  260. </a>
  261. <p align="right">(<a href="#readme-top">back to top</a>)</p>
  262. ## πŸ“„ License
  263. Distributed under the MIT License. See [MIT License](LICENSE) for more information.
  264. ---
  265. <div align="center">
  266. <p><em>Built with ❀️ by <a href="https://themomentum.ai">Momentum</a> β€’ Transforming healthcare data management with AI</em></p>
  267. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

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