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.

Key features:

• Flexible Integration: Use the server from the command line, in Docker, or directly within tools like VS Code, Claude Desktop, and MCP Inspector.
• Natural Language FHIR Search: Query for patients, allergies, immunizations, care plans, and more using simple prompts or programmatic requests.
• Configurable & Secure: Easily connect to any FHIR server, with support for environment-based configuration and secure access tokens.
• Developer Friendly: Quick setup with modern Python tooling (uv), clear documentation, and ready-to-use integration examples for rapid prototyping and deployment.

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.

• Python 3.8+
• uv (for dependency management)
• An accessible FHIR server (defaults to the public HAPI FHIR test server)

1. Clone the repository:

   git clone <repository_url>
   cd <repository_directory>

2. Create a virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate
   uv pip sync requirements.txt

   Or with pip:

   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:

   cp .env.example .env

Run the server:

uv run fhir-mcp-server

You can also run the server directly from the PyPI package (without cloning the repository) using:

uvx fhir-mcp-server

Check available server options:

uvx run fhir-mcp-server --help

Add the following JSON block to your User Settings (JSON) file in VS Code (> V1.101). You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

"mcp": {
    "servers": {
        "fhir": {
            "type": "http",
            "url": "http://localhost:8000/mcp/",
        }
    }
}

"mcp": {
    "servers": {
        "fhir": {
            "type": "sse",
            "url": "http://localhost:8000/sse/",
        }
    }
}

"mcp": {
    "servers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/fhir-mcp-server",
                "run",
                "fhir-mcp-server",
                "--transport",
                "stdio"
            ],
            "env": {
                "HEALTHCARE_MCP_FHIR__ACCESS_TOKEN": "Your FHIR Access Token"
            }
        }
    }
}

Add the following JSON block to your Claude Desktop settings to connect to your local MCP server.

• Launch the Claude Desktop app, click on the Claude menu in the top bar, and select "Settings…".
• 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:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Open the claude_desktop_config.json file in any text editor. Replace its contents with the following JSON block to register the MCP server:

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/mcp"
            ]
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/sse"
            ]
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/fhir-mcp-server",
                "run",
                "fhir-mcp-server",
                "--transport",
                "stdio"
            ],
            "env": {
                "HEALTHCARE_MCP_FHIR__ACCESS_TOKEN": "Your FHIR Access Token"
            }
        }
    }
}

Follow these steps to get the MCP Inspector up and running:

• Open a terminal and run the following command:

  npx -y @modelcontextprotocol/inspector

• In the MCP Inspector interface:

Make sure your MCP server is already running and listening on the above endpoint.

Once connected, MCP Inspector will allow you to visualize tool invocations, inspect request/response payloads, and debug your tool implementations easily.

• get_capabilities: Retrieves metadata about a specified FHIR resource type, including its supported search parameters and custom operations.

  • type: The FHIR resource type name (e.g., "Patient", "Observation", "Encounter")

• search: Executes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources.

  • type: The FHIR resource type name (e.g., "MedicationRequest", "Condition", "Procedure").
  • searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"family":"Simpson","birthdate":"1956-05-12"}).

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

  • type: The FHIR resource type name (e.g., "DiagnosticReport", "AllergyIntolerance", "Immunization").
  • id: The logical ID of a specific FHIR resource instance.
  • searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"device-name":"glucometer"}).
  • operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$everything").

• create: Executes a FHIR "create" interaction to persist a new resource of the specified type.

  • type: The FHIR resource type name (e.g., "Device", "CarePlan", "Goal").
  • payload: A JSON object representing the full FHIR resource body to be created.
  • searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"address-city":"Boston"}).
  • operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$evaluate").

• update: Performs a FHIR "update" interaction by replacing an existing resource instance's content with the provided payload.

  • type: The FHIR resource type name (e.g., "Location", "Organization", "Coverage").
  • id: The logical ID of a specific FHIR resource instance.
  • payload: The complete JSON representation of the FHIR resource, containing all required elements and any optional data.
  • searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"patient":"Patient/54321","relationship":"father"}).
  • operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$lastn").

• delete: Execute a FHIR "delete" interaction on a specific resource instance.

  • type: The FHIR resource type name (e.g., "ServiceRequest", "Appointment", "HealthcareService").
  • id: The logical ID of a specific FHIR resource instance.
  • searchParam: A mapping of FHIR search parameter names to their desired values (e.g., {"category":"laboratory","issued:"2025-05-01"}).
  • operation: The name of a custom FHIR operation or extended query defined for the resource (e.g., "$expand").

• Can you create a new record for Homer Simpson? He's male and was born on 12th of May 1956.
• Record Homer's blood pressure as 120 over 80, taken today at 8 AM.
• Add a lab report for Homer for a fasting glucose test with a result of 5.6 mmol/L.
• Can you add Metformin 500mg to Homer's medications? He needs to take it twice a day.
• Homer is allergic to penicillin and breaks out in a moderate rash, can you add that to his record?
• Update Homer's Metformin dose to 850mg, still twice a day.
• Change Homer's allergy reaction from "moderate" to "mild."
• Show all of Homer's lab results and observations from the past 7 days.
• Delete the penicillin allergy from Homer's record.
• Remove Homer Simpson completely from the system.