Blue Button MCP Server

A FastMCP server for accessing Medicare beneficiary data via the CMS Blue Button 2.0 API. Provides secure FHIR-formatted access to patient demographics, coverage, and claims data through Model Context Protocol.

Prerequisites

• Python 3.11+
• Blue Button API OAuth credentials (sandbox or production)
• Cloud.gov account (for deployment) or local development environment

Setup

1. Register for Blue Button API Access

Sandbox (for development):

1. Go to https://sandbox.bluebutton.cms.gov/v1/accounts/create
2. Create a developer account
3. Register a new application with:
   • Redirect URI: http://localhost:8000/callback (or your deployed URL)
   • Scopes: Select required FHIR scopes (Patient, Coverage, ExplanationOfBenefit)
4. Note your Client ID and Client Secret

Production (requires CMS approval):

1. Complete sandbox testing
2. Apply for production access at https://bluebutton.cms.gov/developers/

2. Install Dependencies

cd blue-button-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

3. Configure Environment

Create a .env file with your Blue Button credentials:

BLUE_BUTTON_CLIENT_ID=your_client_id
BLUE_BUTTON_CLIENT_SECRET=your_client_secret
BASE_URL=http://localhost:8000
USE_SANDBOX=true

4. Run the Server

# Using uvicorn directly
uvicorn server:app --host 0.0.0.0 --port 8000 --reload

# Or with taskipy
task dev

The server will be available at http://localhost:8000

Deployment to Cloud.gov

# Push to cloud.gov
cf push

# Set environment variables
cf set-env blue-button-mcp-server BASE_URL https://blue-button-mcp.app.cloud.gov
cf set-env blue-button-mcp-server BLUE_BUTTON_CLIENT_ID your_client_id
cf set-env blue-button-mcp-server BLUE_BUTTON_CLIENT_SECRET your_client_secret
cf restage blue-button-mcp-server

See manifest.yml for deployment configuration.

Available Tools

Tool	Description
get_patient_info	Get patient demographics (name, address, DOB) - requires patient/Patient.rs scope
get_coverage_info	Get Medicare and supplemental coverage information - requires patient/Coverage.rs scope
get_explanation_of_benefit	Get Medicare claim information (EOB records) - requires patient/ExplanationOfBenefit.rs scope
search_claims	Search claims by date range and type - filters by service date and claim type

Authentication

The server uses OAuth 2.0 authentication via Blue Button API. MCP clients must authenticate through the Blue Button OAuth flow, which provides:

• Access tokens validated against Blue Button's userinfo endpoint
• Automatic extraction of patient ID from token claims
• Scope-based access control to FHIR resources

FHIR Resources

This server exposes data from the following FHIR R4 resources:

• Patient - Demographics and personal information
• Coverage - Medicare coverage details
• ExplanationOfBenefit - Claims and benefit information

Development

# Run tests
task test

# Run linter
task lint

# Format code
task format

# Build package
task build

License

MIT