jcafazzo/fhir-mcp

FHIR MCP Server

A comprehensive Model Context Protocol (MCP) server that provides FHIR (Fast Healthcare Interoperability Resources) functionality with advanced data quality assessment and error handling capabilities.

🎯 Overview

This MCP server bridges the gap between AI applications and FHIR healthcare data systems, providing robust tools for accessing patient information, clinical data, and assessing data quality across different FHIR servers. Perfect for healthcare AI development, clinical research, and testing FHIR implementations.

✨ Key Features

🏥 Comprehensive FHIR Resource Access

• Patient Management: Search, retrieve, and analyze patient demographics
• Clinical Data: Access observations, conditions, medications, diagnostic reports
• Care Coordination: Retrieve care plans and treatment information
• Server Capabilities: Query FHIR server metadata and supported features

🔍 Advanced Data Quality Assessment

• Quality Scoring: 0-100 data quality scores for FHIR servers
• Integrity Checks: Detect orphaned references and disconnected data
• Validation: Comprehensive FHIR response validation
• Issue Detection: Identify data consistency problems automatically

🛡️ Enhanced Error Handling

• HTTP Status Handling: Proper 404, 401, 403, timeout responses
• FHIR OperationOutcome: Standards-compliant error reporting
• Detailed Logging: Request/response debugging information
• Graceful Degradation: Continues operation despite server issues

🧰 Developer-Friendly Tools

• Async Architecture: High-performance async/await implementation
• Pagination Support: Handle large datasets efficiently
• Flexible Configuration: Environment-based server configuration
• MCP Integration: Seamless Claude Desktop integration

🚀 Quick Start

Prerequisites

• Python 3.11 or newer
• Claude Desktop (for MCP integration)

Installation

1. Clone the repository

   git clone https://github.com/jcafazzo/fhir-mcp.git
   cd fhir-mcp
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure Claude Desktop

   Add to your claude_desktop_config.json:

   {
     "mcpServers": {
       "fhir-server": {
         "command": "python3",
         "args": ["/path/to/fhir-mcp/fhir_mcp_server.py"],
         "env": {
           "FHIR_BASE_URL": "https://r4.smarthealthit.org"
         }
       }
     }
   }
   

4. Restart Claude Desktop

🔧 Configuration

Environment Variables

Recommended FHIR Servers

🛠️ Available Tools

Core Patient Tools

• get_patient - Retrieve specific patient by ID
• search_patients - Search patients by name/family
• search_all_patients - Get all patients (paginated)

Clinical Data Tools

• search_observations - Find lab results, vital signs, measurements
• search_conditions - Access diagnoses and medical conditions
• search_medication_requests - Retrieve prescriptions and medications
• search_diagnostic_reports - Get lab reports and diagnostic studies
• search_care_plans - Access treatment and care plans

Quality & Diagnostics

• assess_data_quality - Comprehensive server quality assessment
• find_patients_with_conditions - Identify patients with clinical data
• get_capability_statement - Query server capabilities

📊 Usage Examples

Basic Patient Search

"Search for patients named 'Smith' and show their demographics"

Diabetes Management Workflow

"Find all patients with diabetes conditions, then show their:
- Current medications
- Recent glucose observations  
- Active care plans
- Latest diagnostic reports"

Data Quality Assessment

"Assess the data quality of this FHIR server and identify any issues"

Research Query

"Find patients with conditions containing 'diabetes' and analyze their 
medication patterns over time"

🏥 Healthcare Use Cases

Clinical Research

• Population Studies: Analyze patient cohorts across multiple conditions
• Treatment Outcomes: Track medication effectiveness and care plan adherence
• Data Quality: Validate FHIR implementations before production use

AI Development

• Training Data: Access clean, validated healthcare datasets
• Model Testing: Evaluate AI models against real clinical scenarios
• Integration Testing: Verify FHIR API compatibility

Quality Assurance

• Server Validation: Assess FHIR server implementations
• Data Integrity: Identify orphaned records and missing references
• Compliance Testing: Verify standards adherence

🔒 Security & Privacy

• No PHI Storage: Server operates read-only, no data retention
• Configurable Auth: Support for Bearer token authentication
• Audit Logging: Comprehensive request/response logging
• Error Handling: Secure error responses without data leakage

🧪 Testing

Test Server Quality

# Test different FHIR servers
python3 fhir_mcp_server.py

Use the assess_data_quality tool to evaluate:

• Data completeness (0-100 score)
• Reference integrity
• Resource availability
• Error rates

Synthetic Data Testing

Works excellently with:

• Synthea: Realistic synthetic patient data
• MIMIC-IV FHIR: Real anonymized hospital data
• Custom datasets: Load your own test data

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

# Clone and setup development environment
git clone https://github.com/jcafazzo/fhir-mcp.git
cd fhir-mcp
pip install -r requirements.txt
python3 fhir_mcp_server.py  # Test locally

Roadmap

• Bulk FHIR operations support
• Temporal data analysis tools
• Enhanced MIMIC-IV integration
• Performance optimization
• Additional FHIR resource types

📚 Documentation

• - Claude Code integration guide
• FHIR R4 Specification - Official FHIR documentation
• MCP Protocol - Model Context Protocol specification

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• HL7 FHIR Community for the FHIR specification
• Anthropic for the Model Context Protocol
• SMART Health IT for excellent test servers
• Synthea Project for realistic synthetic data

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Check for detailed setup

Built with ❤️ for the healthcare AI community