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

# Clone the repository
git clone <repository-url>
cd mcp-fhir

# Install dependencies (production only)
uv sync

# For development (includes test tools, linter, etc.)
uv sync --extra dev

# Or with pip
pip install -e .

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:

# Load environment variables from a specific file
uv run fastmcp run server.py --env-file /path/to/your/.env

# Or for development
uv run fastmcp dev server.py --env-file /path/to/your/.env

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

Create a .env file:

cp .env.example .env

Environment Variables

Variable	Default	Description
FHIR_BASE_URL	http://localhost:8080/fhir	FHIR server base URL
FHIR_ALLOW_READ	true	Enable GET operations
FHIR_ALLOW_WRITE	true	Enable POST/PUT/PATCH/DELETE operations
FHIR_AUTH_TOKEN	(empty)	Bearer token for authentication
FHIR_ALLOWED_METHODS	(empty)	Comma-separated HTTP methods (overrides READ/WRITE)

Permission Model

Option 1: Simple Read/Write (default)

FHIR_ALLOW_READ=true   # Enables GET
FHIR_ALLOW_WRITE=true  # Enables POST, PUT, PATCH, DELETE

Option 2: Granular Methods (takes precedence)

FHIR_ALLOWED_METHODS=GET,POST  # Only read and create

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

# Using make (recommended)
make dev

# Or directly
uv run fastmcp dev server.py

Production

# Using make (recommended)
make run

# Or directly
uv run fastmcp run server.py

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

{
  "mcpServers": {
    "fhir": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-fhir",
        "run",
        "fastmcp",
        "run",
        "server.py",
        "--env-file",
        "/absolute/path/to/mcp-fhir/.env"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "fhir": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-fhir",
        "run",
        "fastmcp",
        "run",
        "server.py"
      ],
      "env": {
        "FHIR_BASE_URL": "https://your-fhir-server.com/fhir",
        "FHIR_ALLOW_READ": "true",
        "FHIR_ALLOW_WRITE": "true",
        "FHIR_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

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:

{
  "resourceType": "Patient",
  "name": [{"family": "Smith", "given": ["John"]}],
  "gender": "male"
}

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:

get_patient_zus_upid("John", "Smith")
get_patient_zus_upid("John", "Smith", "builder-123")

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:

Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer {token}  (if FHIR_AUTH_TOKEN set)

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):

{"Zus-Account": "builder-123"}

Timeouts

All requests timeout after 30 seconds.

Error Handling

The server returns detailed errors for:

Code	Description
400	Invalid request/validation error
401	Authentication failed
403	Insufficient permissions
404	Resource or endpoint not found
422	Business rule violation
Timeout	Connection timeout (30s)

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

# Run tests (automatically installs dev dependencies if needed)
make test

# With coverage
make test-cov

# Watch mode
make test-watch

Or directly:

uv run pytest
uv run pytest --cov=. --cov-report=term-missing

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

Code Quality

make lint    # Run linter (automatically installs dev dependencies)
make format  # Format code (automatically installs dev dependencies)
make check   # Lint + format check (automatically installs dev dependencies)

Project Structure

mcp-fhir/
├── server.py          # Generic MCP FHIR server implementation
├── zus_extensions.py  # Zus Health-specific tools (optional)
├── fhir_validator.py  # FHIR validation logic
├── pyproject.toml     # Dependencies
├── .env.example       # Example configuration
└── tests/             # Test suite

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]