MCP FHIR Server

A generic MCP server providing read/write access to any FHIR-compliant API with built-in validation.

This server works with any FHIR server, not just Zus Health. For Zus-specific features (like getting UPIDs), see the Zus Extensions section below.

Features

Core FHIR Features

• FHIR resource validation using consolidated FHIR schemas

• Create and update resources (POST/PUT)

• Read resources by type and ID

• Search resources with query parameters

• Granular permissions via environment configuration

• Bearer token authentication

• Custom HTTP headers for multi-tenant or vendor-specific requirements

• Detailed error messages for debugging and LLM-based correction

Zus Health Extensions (Optional)

• Zus UPID lookup - Get Universal Patient IDs from Zus FHIR servers

• Intelligent name matching - Find best patient match when multiple results exist

• Builder ID support - Multi-tenant access via Zus-Account header

Installation

Prerequisites

• Python 3.13+

• uv (recommended) or pip

Setup

Note: The make commands will automatically install development dependencies when needed, so you can also just run make test directly after cloning.

Configuration

Environment File

The server can load environment variables from a file using the --env-file command line flag:

If no --env-file flag is provided, the server will use system environment variables only.

Create a .env file:

Environment Variables

Permission Model

Option 1: Simple Read/Write (default)

Option 2: Granular Methods (takes precedence)

Examples:

• GET - Read-only

• POST,PUT - Create and update only (no reads)

• GET,POST - Read and create (no updates)

• GET,POST,PUT - Full access

Running

Development

Production

Claude Desktop Integration

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Alternative: You can also set environment variables directly in the config:

Restart Claude Desktop after editing.

Tools

Core FHIR Tools

These tools work with any FHIR-compliant server:

write_fhir_resource

Create or update a FHIR resource.

Parameters:

• resource (object): FHIR resource JSON

• custom_headers (object, optional): Custom HTTP headers for the request

  • For Zus servers: {"Zus-Account": "builder-id"} for multi-tenant access

  • For other servers: Any vendor-specific headers your FHIR server requires

Behavior:

1. Validates resource against FHIR schema

2. Uses POST if no id field (create), PUT if id exists (update)

3. Returns validation errors for correction if invalid

4. Returns server response on success (if FHIR_ALLOW_READ=true)

Example:

Note: If validation schema fails to load, validation is skipped (server-side validation still applies).

read_fhir_resource

Read a resource by type and ID.

Parameters:

• resource_type (string): e.g., "Patient", "Observation"

• resource_id (string): Resource ID

• custom_headers (object, optional): Custom HTTP headers for the request

Returns: JSON resource or error message

search_fhir_resources

Search resources with query parameters.

Parameters:

• resource_type (string): Resource type to search

• search_params (object, optional): Query parameters

  • Example: {"name": "Smith", "gender": "female"}

• custom_headers (object, optional): Custom HTTP headers for the request

Returns: FHIR Bundle with matching resources

get_fhir_config

View current configuration.

Returns: Configuration summary including base URL, permissions, and allowed methods.

Zus Health Extensions

These tools are specific to Zus Health FHIR servers and will not work with other FHIR implementations.

get_patient_zus_upid

Get the Zus UPID (Universal Patient ID) for a Patient resource from Zus FHIR server.

Parameters:

• first_name (string): Patient's first name

• last_name (string): Patient's last name

• builder_id (string, optional): Zus builder ID to filter the search

Behavior:

1. Searches for Patient resources using name parameter (concatenated first and last name)

2. Optionally filters by Zus builderID parameter if provided

3. Extracts Zus UPID from Patient's identifiers with system https://zusapi.com/fhir/identifier/universal-id

4. When multiple patients are found, uses intelligent name matching to find the best match

5. Returns the Zus UPID value or appropriate error message

Example usage:

Response formats:

• Single patient found: Zus UPID: zus-upid-12345

• Multiple patients with good name match: Zus UPID: zus-upid-12345 (Best match: John Smith) + other matches if any

• Multiple patients with no clear match: Lists all found patients with their Zus UPIDs

• No patients found: Error: No Patient found with name 'John Smith'

• No Zus UPID: Error: No Zus UPID found for Patient(s) with name 'John Smith'

Name Matching Logic:

• Exact name matches get highest priority (score 1.0)

• Partial matches (e.g., "John" matching "Johnny") get medium priority (score 0.7 for given name)

• Family name matches are weighted more heavily than given name matches

• Partial matches are permissive: shorter names can match longer ones (e.g., "John" matches "Johnny")

• If the best match has a score ≥ 0.5, it's returned as the primary result

• Other decent matches (score ≥ 0.3) are listed as alternatives

Technical Details

HTTP Headers

All requests include:

Custom Headers: You can provide additional custom headers via the custom_headers parameter in any tool. This is useful for:

• Multi-tenant systems (e.g., Zus's Zus-Account header)

• Vendor-specific authentication or routing headers

• Any other FHIR server-specific requirements

Example (Zus):

Timeouts

All requests timeout after 30 seconds.

Error Handling

The server returns detailed errors for:

Errors include full server response when available for debugging.

Validation

Resources are validated using the fhir-validator library before submission:

• Checks FHIR spec compliance

• Validates required fields and data types

• Verifies resource structure

If validation schema loading fails at startup, a warning is logged and validation is bypassed (server-side validation still occurs).

Development

Testing

Or directly:

Note: All make commands automatically install development dependencies when needed, so new developers can simply run make test after cloning the repository.

Code Quality

Project Structure

Architecture

The server is designed with modularity in mind:

• server.py: Contains generic FHIR operations that work with any FHIR server

• zus_extensions.py: Contains Zus Health-specific functionality (UPID lookup, etc.)

• Generic tools accept custom_headers for flexibility with different FHIR vendors

• Zus tools use builder_id for Zus-specific multi-tenancy

This separation allows you to:

1. Use the generic tools with any FHIR server

2. Add your own vendor-specific extensions by following the zus_extensions.py pattern

3. Keep the core FHIR functionality clean and standards-compliant

License

[Add license information]

Contributing

[Add contribution guidelines]