Healthcare Analytics MCP Server

Healthcare Analytics MCP Server

A comprehensive Model Context Protocol (MCP) server for healthcare data analysis using Tuva Health demo data. This server provides tools for value-based care analytics, quality measures, utilization analysis, and financial metrics commonly used in healthcare organizations.

Motivation

To get a quick MCP setup that can be used to service most of the common data questions that get floated over to analysts and are simple data pulls. Something like this could be utilized at healthcare companies to free up time for analysts to work on more complicated analytics, while also providing well-defined queries to be reused across an org.

• The Tuva Project provides dbt project to build a typical database setup that translates well across the industry.
• Warp (I think it was using Sonnet) did pretty well with the initial setup. I had the demo data loaded to bigquery and MCP toolbox for databases set up so it could get context from the existing tables. The queries were wrong, but only required minimal fixes. The scaffolding is there for analysts to write official queries to be used by the server.

Features

Core Analytics Tools

• Patient Demographics: Age groups, gender distribution, enrollment analysis
• Utilization Summary: Claims analysis, service category breakdown
• PMPM Analysis: Per Member Per Month financial metrics with trends
• Quality Measures: HEDIS and clinical quality indicator tracking
• Chronic Conditions: Prevalence analysis and condition family insights
• High-Cost Patients: Case management identification
• Readmissions Analysis: 30-day readmission patterns
• HCC Risk Scores: Risk adjustment and stratification

Value-Based Care Metrics

• Risk-adjusted cost analysis
• Quality performance tracking
• Population health insights
• Care gap identification
• Financial performance monitoring

Setup

Option 1: Docker Deployment (Recommended)

The easiest way to use this MCP server is with the pre-built Docker image from GitHub Container Registry.

Prerequisites

• Docker installed on your machine
• MCP-compatible client (Claude Desktop, Warp, etc.)
• Google Cloud Project with BigQuery API enabled
• Tuva Health demo data loaded in BigQuery
• Service account with BigQuery access

Docker Authentication Options

Option A: Service Account Key (Recommended)

Configure your MCP client (e.g., Claude Desktop) with:

Option B: Application Default Credentials (ADC)

If you've authenticated with gcloud auth application-default login:

Replace the placeholders:

• your-home-directory with your home directory (/Users/dslans)
• /path/to/your/service-account.json with your actual service account file path (Option A)
• your-gcp-project-id with your Google Cloud Project ID (For example prj-tuva-demo)
• your-dataset-prefix with your BigQuery dataset prefix (Can be just the project name ending with . like prj-tuva-demo. or leave blank)

Restart your MCP client and start using the healthcare analytics tools!

Option 2: Local Installation

For developers who want to run the MCP server locally or customize the code.

Prerequisites

• Python 3.9+
• MCP-compatible client (Claude Desktop, Warp, etc.)
• Google Cloud Project with BigQuery API enabled
• Tuva Health demo data loaded in BigQuery
• Service account with BigQuery access

Installation Steps

1. Clone the repository:

2. Install Python dependencies:

3. Set up environment variables:

4. Configure your .env file:

5. Test the server:

6. Configure your MCP client:

7. Restart your MCP client and start using the healthcare analytics tools!

Local Development Authentication

Option A: Service Account Key

• Download and configure as shown in the Google Cloud Authentication section below

Option B: Application Default Credentials

Google Cloud Authentication

Create Service Account

1. Create a service account:

2. Grant BigQuery permissions:

3. Download service account key:

Available Tools

1. Patient Demographics Analysis

Returns demographic breakdown including age groups, gender distribution, and total patient counts.

2. Healthcare Utilization Summary

Provides comprehensive utilization metrics including claims counts, costs, and service category breakdowns.

3. PMPM Financial Analysis

Calculates Per Member Per Month costs across different service categories with trend analysis.

4. Quality Measures Summary

Returns quality measure performance rates and compliance flags for HEDIS and clinical measures.

5. Chronic Conditions Prevalence

Analyzes prevalence rates for chronic conditions across the patient population.

6. High-Cost Patient Identification

Identifies patients exceeding cost thresholds for case management prioritization.

7. Readmissions Analysis

Calculates 30-day readmission rates and patterns for quality improvement.

8. HCC Risk Score Analysis

Provides HCC risk score distribution and population risk stratification.

Data Requirements

The server expects Tuva Health formatted data with the following key datasets:

• core.* - Claims, patient, eligibility, and encounter data
• quality_measures.* - HEDIS and clinical quality measures
• financial_pmpm.* - Per Member Per Month financial calculations
• chronic_conditions.* - Chronic condition classifications
• cms_hcc.* - HCC risk adjustment data
• readmissions.* - Readmission analysis results

Example Use Cases

Value-Based Care Analytics

Monthly Performance Reporting

Example Questions

Once your MCP server is configured, you can ask natural language questions in your MCP client (Claude Desktop, Warp, etc.). Here are some examples:

📊 Population Health & Demographics

• "Show me the patient demographics for 2018, including age group breakdowns"
• "What's the gender distribution of our patient population?"
• "How many patients do we have enrolled and what's the average age?"

💰 Financial & Cost Analysis

• "Calculate the PMPM costs for all service categories in 2018"
• "Who are our highest cost patients above $20,000 in total spend?"
• "Show me per-member-per-month analysis for Medicare patients only"
• "What are the top 10 most expensive service categories by total cost?"

🏥 Healthcare Utilization

• "Analyze healthcare utilization patterns for 2018"
• "Show me Emergency Department utilization statistics"
• "What's the breakdown of claims by service category?"
• "How many unique patients had medical claims last year?"

📈 Quality Measures & Performance

• "What are our quality measure performance rates for 2018?"
• "Show me diabetes medication adherence scores"
• "Analyze our HEDIS quality measures and compliance rates"
• "Which quality measures are we performing well on vs. need improvement?"

🩺 Clinical Analytics

• "What's the prevalence of chronic conditions in our population?"
• "Show me diabetes prevalence rates and patient counts"
• "Analyze 30-day readmission rates by condition category"
• "What are the readmission patterns for heart failure patients?"

🎯 Risk Adjustment & HCC

• "Calculate HCC risk scores for our patient population"
• "Show me risk score distribution and identify high-risk patients"
• "Who are the patients with the highest risk adjustment scores?"

🔍 Care Management

• "Identify patients for case management based on high costs and readmissions"
• "Which patients have both high costs and multiple chronic conditions?"
• "Show me patients with diabetes who also have high utilization"

📅 Trend Analysis

• "Compare January 2018 PMPM costs to December 2018"
• "Show me quarterly utilization trends throughout 2018"
• "How did our quality measures change over the year?"

🏢 Business Intelligence

• "Generate a comprehensive population health report for 2018"
• "What insights can you provide about our highest cost drivers?"
• "Summarize our value-based care performance metrics"
• "Create an executive summary of our healthcare analytics"

These questions will automatically trigger the appropriate MCP tools and return structured healthcare analytics data that can be used for reporting, decision-making, and care management.

Development

Publishing Docker Image

To make the Docker image available for users:

1. Push to GitHub:

2. GitHub Actions will automatically:
   • Build the Docker image
   • Push to GitHub Container Registry (GHCR)
   • Make it available at ghcr.io/yourusername/mcp_healthcare_data:latest
3. Check the Actions tab in your GitHub repo to monitor the build progress.
4. Once published, users can pull the image:

Local Testing

Adding New Tools

To add new healthcare analytics tools:

1. Create a new function with the @mcp.tool() decorator
2. Add proper type hints and documentation
3. Use the execute_query() helper for BigQuery operations
4. Return structured data as dictionaries

Example:

Troubleshooting

Common Issues

1. Authentication Errors: Ensure your service account key path is correct in .env
2. Dataset Not Found: Verify your BIGQUERY_DATASET_PREFIX matches your data location
3. Permission Denied: Confirm your service account has BigQuery viewer/user roles
4. Python Version Errors: Ensure you're using Python 3.9+ (pandas 2.2.2 and numpy 1.26.4 require 3.9+)
5. Import Errors: Ensure all dependencies are installed with uv pip install -r requirements.txt
6. Docker Issues: Check that Docker is running and you have sufficient disk space

Docker Troubleshooting

"denied" error when pulling from GHCR:

This means:

1. The image hasn't been published yet (push to GitHub to trigger build)
2. The repository is private (make it public or authenticate)
3. Wrong username/repository name in the image URL

Other Docker issues: