FHIR MCP Server

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

📋 Table of Contents

• 🔍 About
• 💡 Demo
• 🚀 Getting Started
• 📝 Usage
• 🔧 Configuration
• 🐳 Docker Setup
• 🛠️ MCP Tools
• 🗺️ Roadmap
• 👥 Contributors
• 📄 License

🔍 About The Project

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.

✨ Key Features

• 🚀 FastMCP Framework: Built on FastMCP for high-performance MCP server capabilities
• 🏥 FHIR Resource Management: Full CRUD operations for all major FHIR resources
• 📄 Intelligent Document Processing: AI-powered document ingestion and chunking for multiple formats including TXT, CSV, JSON, and PDF
• 🔍 Semantic Search: Advanced document search using vector embeddings (via Pinecone)
• 🧠 RAG-Ready: Retrieval-Augmented Generation pipeline with context-aware document queries
• 🔐 Secure Authentication: OAuth2 token management for FHIR API integration
• 📊 LOINC Integration: Standardized medical terminology lookup and validation
• 🐳 Container Ready: Docker support for easy deployment and scaling
• 🔧 Configurable: Extensive .env-based configuration options

🏗️ Architecture

The server is built with a modular architecture:

• MCP Tools: Dedicated tools for selected FHIR resource types, with others handled by a generic tool
• Fhir Server Client: Handles FHIR API communication and authentication (OAuth2 and more planned)
• RAG Services: Embedding-based document processing and semantic retrieval
• Vector Store: Pinecone integration for similarity-based search
• LOINC Client: Integration with LOINC API for terminology resolution and validation

(back to top)

💡 Demo

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:

• utilization of the request_patient_resource tool which retrieves basic patient information
• 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
• 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

You can observe how Claude automatically selects the tools worth using to answer the question based on the user's query.

https://github.com/user-attachments/assets/3a3a8ed3-f881-447d-af03-5f24432a2cdd

🚀 Getting Started

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

Prerequisites

• Docker (recommended) or uv: For dependency management

  👉 uv Installation Guide

• 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

• 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

Installation & Setup

1. Clone the repository:

   sh

   Copy

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

2. Set up environment variables:

   sh

   Copy

   cp config/.env.example config/.env
   

   Edit the config/.env file with your credentials and configuration. See Environment Variables

3. Install Dependencies

   For Docker-based execution run:

   sh

   Copy

   make build
   

   For uv-based execution run:

   sh

   Copy

   make uv
   

4. Update the MCP Client configuration

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

• Docker

  config.json

  Copy

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

    Code

    Copy

    (Get-Command uv).Path
    

  • MacOS/Linux:

    Code

    Copy

    which uv
    

  Then, update config file:

  config.json

  Copy

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

  Make sure to replace 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

(back to top)

🔧 Configuration

🔐 Security & Encryption

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.

You are allowed to store passwords as a plain text, but if you want to have them encrypted, follow the instruction below.

Setting Up Encryption

# uv method
uv run scripts/cryptography/setup_encryption.py

# docker method
docker exec fhir-mcp-server uv run scripts/cryptography/setup_encryption.py