Skip to main content

FHIR Inspector MCP

A production-ready Model Context Protocol (MCP) server for inspecting, validating, and generating FHIR resources. Supports FHIR R4 and R5 specifications with zero external dependencies at runtime.

Features

  • inspect_resource — Parse and display FHIR resource structure, elements, types, cardinalities, and references
  • validate_resource — Validate FHIR resources against R4/R5 profiles with detailed error reporting and JSON paths
  • summarize_bundle — Analyze FHIR bundles (transaction, searchset, document, batch, etc.) with statistics and reference graphs
  • generate_example — Create valid FHIR resource examples for any resource type with optional overrides

Installation Methods

Method Description
uvx (Recommended) Run directly with automatic updates via uvx fhir-inspector-mcp@latest
pipx Install as isolated CLI tool with pipx install fhir-inspector-mcp
Docker Run in container with docker run -i ghcr.io/cytocync/fhir-inspector-mcp:latest
From Source Clone and install for development with uv sync

Add to your MCP client's mcpServers configuration:

{
  "mcpServers": {
    "fhir-inspector-mcp": {
      "command": "uvx",
      "args": ["fhir-inspector-mcp@latest"],
      "env": {
        "UV_HTTP_TIMEOUT": "300"
      }
    }
  }
}

The @latest tag enables automatic updates. The server starts instantly with no browser or authentication required — it's a pure Python stdio server.


Client-Specific Setup

Claude Desktop

Option 1: MCP Settings File

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fhir-inspector-mcp": {
      "command": "uvx",
      "args": ["fhir-inspector-mcp@latest"]
    }
  }
}

Option 2: Using pipx

pipx install fhir-inspector-mcp

Then configure:

{
  "mcpServers": {
    "fhir-inspector-mcp": {
      "command": "fhir-inspector-mcp"
    }
  }
}

Restart Claude Desktop after editing the config.

Cursor

Via Cursor Settings (UI)

  1. Open Cursor Settings → MCP → Add new MCP server
  2. Name: fhir-inspector-mcp
  3. Command: uvx
  4. Args: fhir-inspector-mcp@latest

Via .cursor/mcp.json

{
  "mcpServers": {
    "fhir-inspector-mcp": {
      "command": "uvx",
      "args": ["fhir-inspector-mcp@latest"]
    }
  }
}

VS Code (with MCP Extension)

Add to .vscode/mcp.json:

{
  "servers": {
    "fhir-inspector-mcp": {
      "command": "uvx",
      "args": ["fhir-inspector-mcp@latest"]
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "mcpServers": {
    "fhir-inspector-mcp": {
      "command": "uvx",
      "args": ["fhir-inspector-mcp@latest"]
    }
  }
}

Codex (OpenAI)

codex plugin marketplace add cytocync/fhir-inspector-mcp
codex plugin add fhir-inspector-mcp@fhir-inspector-mcp

Claude Code

claude plugin marketplace add cytocync/fhir-inspector-mcp
claude plugin install fhir-inspector-mcp@fhir-inspector-mcp

Docker

{
  "mcpServers": {
    "fhir-inspector-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/cytocync/fhir-inspector-mcp:latest"]
    }
  }
}

Or run directly:

docker run -i --rm ghcr.io/cytocync/fhir-inspector-mcp:latest

Tool Reference

inspect_resource

Parse and display FHIR resource structure with element tree, types, cardinalities, and references.

Parameters:

Parameter Type Default Description
resource string required FHIR resource as JSON string
version string "R4" FHIR version: "R4" or "R5"
max_depth integer 5 Maximum depth for element tree (1-10)
include_types boolean true Include FHIR type metadata in output

Example:

{
  "resource": "{"resourceType": "Patient", "id": "example", "name": [{"family": "Doe", "given": ["John"]}]}",
  "version": "R4",
  "max_depth": 3
}

Response:

{
  "success": true,
  "data": {
    "resource_type": "Patient",
    "fhir_version": "R4",
    "element_tree": [
      {"path": "Patient.id", "type": "id", "required": false, "repeated": false},
      {"path": "Patient.name", "type": "HumanName", "required": false, "repeated": true},
      {"path": "Patient.name[0].family", "type": "string", "required": true, "repeated": false},
      {"path": "Patient.name[0].given", "type": "string", "required": false, "repeated": true}
    ],
    "references": [],
    "contained": [],
    "summary": {"total_elements": 4, "depth_reached": 2}
  },
  "issues": [],
  "meta": {
    "fhir_version": "R4",
    "resource_type": "Patient",
    "duration_ms": 12.4,
    "truncated": false
  }
}

validate_resource

Validate FHIR resources against R4/R5 structural profiles with detailed error reporting.

Parameters:

Parameter Type Default Description
resource string required FHIR resource as JSON string
version string "R4" FHIR version: "R4" or "R5"

Example:

{
  "resource": "{"resourceType": "Observation", "id": "obs1", "status": "final", "code": {"coding": [{"system": "http://loinc.org", "code": "8480-6"]}}, "subject": {"reference": "Patient/example"}}",
  "version": "R4"
}

Response (valid):

{
  "success": true,
  "data": {
    "valid": true,
    "error_count": 0,
    "warning_count": 0
  },
  "issues": [],
  "meta": {
    "fhir_version": "R4",
    "resource_type": "Observation",
    "duration_ms": 8.2,
    "truncated": false
  }
}

Response (invalid):

{
  "success": false,
  "data": {
    "valid": false,
    "error_count": 1,
    "warning_count": 0
  },
  "issues": [
    {
      "severity": "error",
      "code": "E_VALIDATION_FAILED",
      "path": "Observation.status",
      "message": "Field required [type=missing, input_value={...}, input_type=dict]"
    }
  ],
  "meta": {
    "fhir_version": "R4",
    "resource_type": "Observation",
    "duration_ms": 5.1,
    "truncated": false
  }
}

summarize_bundle

Analyze FHIR bundles with entry counts, resource type distributions, and reference graphs.

Parameters:

Parameter Type Default Description
bundle string required FHIR Bundle as JSON string
version string "R4" FHIR version: "R4" or "R5"
include_references boolean true Include bounded reference graph in output
max_entries integer 10000 Maximum entries to process (1-10000)

Example:

{
  "bundle": "{"resourceType": "Bundle", "type": "transaction", "entry": [{"request": {"method": "POST", "url": "Patient"}, "resource": {"resourceType": "Patient", "id": "p1"}}]}",
  "version": "R4",
  "include_references": true
}

Response:

{
  "success": true,
  "data": {
    "bundle_type": "transaction",
    "total": null,
    "entry_count": 1,
    "truncated": false,
    "resource_type_counts": {"Patient": 1},
    "request_method_counts": {"POST": 1},
    "references": [],
    "contained_count": 0
  },
  "issues": [],
  "meta": {
    "fhir_version": "R4",
    "resource_type": "Bundle",
    "duration_ms": 15.7,
    "truncated": false
  }
}

generate_example

Create valid FHIR resource examples for any resource type with optional field overrides.

Parameters:

Parameter Type Default Description
resource_type string required FHIR resource type (e.g., "Patient", "Observation")
version string "R4" FHIR version: "R4" or "R5"
overrides object null Flat dotted-path overrides (e.g., {"name.0.family": "Smith"})

Example:

{
  "resource_type": "Patient",
  "version": "R4",
  "overrides": {
    "name.0.family": "Smith",
    "gender": "female",
    "birthDate": "1990-05-15"
  }
}

Response:

{
  "success": true,
  "data": {
    "resource_type": "Patient",
    "fhir_version": "R4",
    "resource": "{"resourceType":"Patient","id":"example","name":[{"family":"Smith","given":["Test"]}],"gender":"female","birthDate":"1990-05-15"}",
    "validated": true
  },
  "issues": [],
  "meta": {
    "fhir_version": "R4",
    "resource_type": "Patient",
    "duration_ms": 23.1,
    "truncated": false
  }
}

Error Codes

All tools return a unified response envelope with structured issues:

Code Severity Description
E_INVALID_JSON error Payload is not parseable JSON
E_UNSUPPORTED_VERSION error Version not in {R4, R5}
E_UNKNOWN_RESOURCE_TYPE error Resource type not found in selected version
E_VALIDATION_FAILED error Structural validation failed
E_NOT_A_BUNDLE error summarize_bundle called on non-Bundle resource
E_GENERATION_FAILED error Generator could not produce valid instance
E_PAYLOAD_TOO_LARGE error JSON payload exceeds 10 MB
E_DEPTH_EXCEEDED error JSON nesting exceeds 50 levels
E_ENTRY_LIMIT error Bundle entries exceed limit
W_VERSION_ASSUMED warning Default version (R4) was used
W_OUTPUT_TRUNCATED warning Results truncated due to node/entry caps

Unknown resource types include close-match suggestions for self-correction.


Development

Prerequisites

  • Python 3.12+
  • uv (recommended) or pip

Install from Source

# Clone repository
git clone https://github.com/CytoCync/fhir-inspector-mcp.git
cd fhir-inspector-mcp

# Install dependencies
uv sync --dev

# Run server directly
uv run fhir-inspector-mcp

# Run tests
uv run pytest --cov

Project Structure

src/fhir_inspector_mcp/
├── __main__.py          # Entry point
├── server.py            # FastMCP server setup
├── tools.py             # 4 @mcp.tool wrappers
├── models.py            # Response envelope & Issue models
└── core/
    ├── __init__.py
    ├── limits.py        # Guardrail constants
    ├── registry.py      # Version/type resolution
    ├── parser.py        # JSON parsing + validation
    ├── inspection.py    # Element tree extraction
    ├── validation.py    # Validation wrapper
    ├── summarizer.py    # Bundle summarization
    └── generation.py    # Example generation

Testing

# All tests with coverage
uv run pytest --cov=fhir_inspector_mcp --cov-report=term-missing

# Unit tests only
uv run pytest tests/unit/

# Integration tests only
uv run pytest tests/integration/

# Property-based tests
uv run pytest tests/property/

License

MIT License — see LICENSE for details.

Contributing

See CONTRIBUTING.md for guidelines.

See docs/development.md for development setup, testing, and code quality instructions.


Security

This server:

  • Runs as stdio-only (no network listener)
  • Enforces 10 MB payload limit, 50-level depth limit, 10k bundle entry cap
  • Validates all inputs with allowlist regex before dynamic imports
  • Never dereferences FHIR Reference URLs (no SSRF)
  • Uses only synthetic test data (no PHI)
  • Runs pip-audit in CI for vulnerability scanning

Report security issues via GitHub Security Advisories.

Metadata

Release files for fhir-inspector-mcp 0.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fhir-inspector-mcp 0.0.6
File Size Uploaded Provenance Actions
fhir_inspector_mcp-0.0.6.tar.gz 25.0 kB Without provenance Details for fhir_inspector_mcp-0.0.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fhir-inspector-mcp 0.0.6
File Interpreter ABI Platform Actions
fhir_inspector_mcp-0.0.6-py3-none-any.whl Python 3 none any Details for fhir_inspector_mcp-0.0.6-py3-none-any.whl

Total release size: 50.9 kB

Release files / fhir_inspector_mcp-0.0.6.tar.gz

Download URL fhir_inspector_mcp-0.0.6.tar.gz
Size 25.0 kB
Tags Source
SHA-256 checksum
How to use checksums
76b8239f429652015d3c2794029b13ce321d7e1e82814840ea40eb610044e056
BLAKE2b-256 checksum
How to use checksums
33dbd91947450f8da31253c1a07268c106d4023459d3aad84f74ee031adadfeb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / fhir_inspector_mcp-0.0.6-py3-none-any.whl

Download URL fhir_inspector_mcp-0.0.6-py3-none-any.whl
Size 25.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
450be58887c1ff76107eb433ed49a667023e1dea60ac068a86ce65c40e5ae0f8
BLAKE2b-256 checksum
How to use checksums
690dab166f76cb06733c404114799b9ba8a14720b1fc54b9c353dd53dd3a13a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for fhir-inspector-mcp 0.0.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.6 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page