trobanga/blaze-mcp

Blaze MCP Server

An MCP (Model Context Protocol) server that enables AI assistants like Claude to interact with Blaze FHIR Server through natural language.

Overview

This server exposes Blaze's FHIR capabilities to AI agents, allowing them to:

• Search and retrieve patient data
• Execute CQL-based quality measures
• Validate terminology codes
• Manage FHIR resources
• Query multiple Blaze instances dynamically

Quick Start

Run directly from GitHub (no installation)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "blaze": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/trobanga/blaze-mcp", "blaze-mcp"]
    }
  }
}

Then ask Claude: "Connect to Blaze at http://localhost:8080/fhir and search for patients"

Alternative: From local directory

{
  "mcpServers": {
    "blaze": {
      "command": "uv",
      "args": ["--directory", "/path/to/blaze-mcp", "run", "blaze-mcp"]
    }
  }
}

Alternative: Install with pip

pip install git+https://github.com/trobanga/blaze-mcp
# or from local clone
pip install -e /path/to/blaze-mcp

Then use:

{
  "mcpServers": {
    "blaze": {
      "command": "blaze-mcp"
    }
  }
}

Client Configuration

Claude Code / Claude Desktop

Add to ~/.claude/settings.json (Claude Code) or Claude Desktop config:

{
  "mcpServers": {
    "blaze": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/trobanga/blaze-mcp", "blaze-mcp"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "blaze": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/trobanga/blaze-mcp", "blaze-mcp"]
    }
  }
}

Or use the Gemini CLI command:

gemini mcp add blaze uvx --from git+https://github.com/trobanga/blaze-mcp blaze-mcp

Note: Requires uv to be installed.

See Gemini CLI MCP documentation for more options.

Features

Tools

Resources

Prompts

Configuration

All settings can be configured via environment variables:

Usage

With Claude Desktop

Add to your config file:

• Linux: ~/.config/claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blaze": {
      "command": "blaze-mcp",
      "env": {
        "BLAZE_MCP_BLAZE_BASE_URL": "http://localhost:8080/fhir"
      }
    }
  }
}

With Claude Code

{
  "mcpServers": {
    "blaze": {
      "command": "blaze-mcp"
    }
  }
}

Dynamic URL (Multiple Blaze Instances)

The Blaze URL can be changed at runtime - no restart needed:

User: "Connect to the production Blaze at https://blaze.hospital.org/fhir"
Claude: [uses set_blaze_url tool]
        "Connected to https://blaze.hospital.org/fhir"

User: "How many patients are there?"
Claude: [uses get_totals tool]
        "There are 50,432 patients..."

User: "Now check the staging server at http://staging:8080/fhir"
Claude: [uses set_blaze_url tool]
        ...

SSE Transport (Network Mode)

Run as an HTTP service for containerized or remote deployments:

blaze-mcp --transport sse --port 8000

Endpoints:

• http://localhost:8000/sse - SSE connection
• http://localhost:8000/messages/ - Message endpoint

Docker

docker build -t blaze-mcp .

docker run -d \
  -p 8000:8000 \
  -e BLAZE_MCP_BLAZE_BASE_URL=http://blaze:8080/fhir \
  blaze-mcp

Docker Compose

services:
  blaze:
    image: samply/blaze:latest
    ports:
      - "8080:8080"
    volumes:
      - blaze-data:/app/data

  blaze-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      BLAZE_MCP_BLAZE_BASE_URL: http://blaze:8080/fhir
    depends_on:
      - blaze

volumes:
  blaze-data:

Example Conversations

Once configured, you can interact naturally:

"Connect to Blaze at http://192.168.1.50:8080/fhir"

"Search for all patients with diabetes"

"Get the complete medical record for patient 12345"

"Find observations for patient 12345 from the last year"

"Validate the LOINC code 8480-6"

"How many resources are in the database?"

"Evaluate the diabetes-screening measure for 2024"

"Create a new Patient resource with name John Doe"

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/

# Linting
ruff check src/
ruff format src/

Architecture

┌─────────────────┐                     ┌─────────────────┐
│   AI Assistant  │  ←── MCP Protocol ──│   blaze-mcp     │
│   (Claude)      │      (stdio/SSE)    │                 │
└─────────────────┘                     └────────┬────────┘
                                                 │
                                                 │ HTTP/FHIR
                                                 ▼
                                        ┌─────────────────┐
                                        │     Blaze       │
                                        │  FHIR Server    │
                                        └─────────────────┘

License

Apache 2.0

Links

• Blaze FHIR Server
• Model Context Protocol
• FHIR R4 Specification