FHIR-MCP - FHIR Model Context Protocol Server

FHIR-MCP is an open-source MCP (Model Context Protocol) server that enables LLMs to securely interact with FHIR servers and HL7 terminology services. It provides a comprehensive toolset for healthcare interoperability with enterprise-grade security hardening, PHI protection, audit logging, and token-efficient operations.

✨ Features

• 🔐 Enterprise Security: OWASP-compliant hardening with multi-tier rate limiting

• 🛡️ PHI Protection: Advanced masking, classification, and redaction of sensitive healthcare data

• 📊 Comprehensive FHIR Support: Read, search, create, and update operations

• 🏥 HL7 Terminology: ValueSet expansion, CodeSystem lookup, and concept translation

• 📝 Audit Logging: HIPAA-compliant audit trail with structured logging and trace IDs

• ⚡ Token Efficient: Field selection, pagination, and optimized queries

• 🔧 Interoperable: Works with HAPI FHIR, Firely, and other R4/R4B servers

• ✅ Production Ready: Security hardening Phase 1 complete with comprehensive validation

• 🌐 HTTP Bridge: Secure REST API with Docker containerization support

• 🔒 Modern Architecture: ES modules, TypeScript, and cloud-native deployment

🚀 Quick Start

1. Install dependencies:

   npm install

2. Build the project:

   npm run build

3. Configure environment:

   export FHIR_BASE_URL="https://hapi.fhir.org/baseR4" export TERMINOLOGY_BASE_URL="https://tx.fhir.org/r4" export PHI_MODE="safe"

4. Start the server:

   cd packages/mcp-fhir-server npm start

5. Test functionality:

   node test-basic-functionality.js

🛠️ Available Tools

FHIR Operations

• fhir.capabilities - Get server capability statement

• fhir.search - Search resources with advanced filtering

• fhir.read - Read specific resources by ID

• fhir.create - Create new FHIR resources

• fhir.update - Update existing resources

Terminology Services

• terminology.lookup - Look up code properties and display names

• terminology.expand - Expand ValueSets to get contained codes

• terminology.translate - Translate codes between coding systems

📁 Project Structure

🔒 Security Features (Phase 1 Complete)

Enterprise Security Hardening

• OWASP Compliance: Complete security headers and content security policies

• Multi-Tier Rate Limiting: PHI-aware rate limiting with progressive delays

• Input Validation: Comprehensive Joi-based validation with SQL injection prevention

• Request Monitoring: Suspicious activity detection with automated IP blocking

• Emergency Access: Break-glass mechanisms for critical healthcare scenarios

PHI Protection & Classification

• Advanced PHI Engine: ML-powered classification of sensitive healthcare data

• Safe Mode: Automatically masks names, addresses, birth dates, and identifiers

• Trusted Mode: Returns data as-is for secure environments

• Dynamic Masking: Context-aware redaction based on PHI sensitivity levels

• Authorization Engine: Role-based access control with healthcare-specific permissions

Audit & HIPAA Compliance

• Comprehensive Audit Trail: Structured logging with trace IDs for all operations

• PHI-Safe Logging: Automatic redaction of sensitive data in audit logs

• FHIR AuditEvent Support: Standards-compliant audit event emission

• Security Monitoring: Real-time threat detection and response

• Compliance Reporting: Automated generation of security and access reports

Authentication & Authorization

• SMART on FHIR / OAuth2: Authorization Code + PKCE flow support

• Client Credentials: Server-to-server access with scope validation

• Emergency Override: Break-glass access for critical patient care situations

• Session Management: Secure token handling with automatic expiration

📖 Documentation

• Quick Start Guide - Installation and basic usage

• Prompt Library - Ready-to-use LLM prompts and patterns

• Security Guide - Production deployment and security considerations

🧪 Testing

Run the test suites:

QA Test Results: ✅ 19/19 tests passed (100% success rate)

• All core functions validated

• Security features verified

• PHI protection tested

• Audit logging validated

• ES module compatibility confirmed

See QA-REPORT.md for detailed test results.

🔧 Configuration

Configure via environment variables:

🤖 Using with Claude

Add FHIR-MCP to your Claude MCP configuration:

🌐 HTTP Bridge for Web Applications

For browser-based AI assistants that can't use MCP directly:

Local Development

Docker Deployment (Recommended)

The bridge provides secure REST endpoints at http://localhost:3002 (or localhost:3001 for local dev):

• GET /health - Health check with security status

• GET /tools - List available tools

• POST /fhir/capabilities - FHIR server capabilities

• POST /fhir/search - Search FHIR resources

• POST /fhir/read - Read FHIR resources

• POST /fhir/create - Create FHIR resources (write operations)

• POST /fhir/update - Update FHIR resources (write operations)

• POST /terminology/lookup - Terminology lookup

• POST /terminology/expand - ValueSet expansion

• POST /terminology/translate - Code translation

• POST /tools/{toolName} - Generic tool interface

Security Features Active

• ✅ OWASP security headers

• ✅ Multi-tier rate limiting

• ✅ Input validation & sanitization

• ✅ PHI-aware authorization

• ✅ Comprehensive audit logging

• ✅ Emergency access controls

📋 Roadmap

• MVP: Basic FHIR operations and terminology lookup

• QA: Comprehensive testing and security validation

• ES Modules: Modern JavaScript module support

• HTTP Bridge: Web-accessible REST API

• Phase 1 Security: Enterprise hardening with PHI protection

• Docker: Containerized deployment with security hardening

• Phase 2: OAuth2 flows, advanced policy engine

• Phase 3: Delete operations, bulk export, R5 support

• Future: GraphQL support, subscription webhooks

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• HL7 FHIR for the interoperability standard

• Model Context Protocol for the protocol specification

• HAPI FHIR for the reference implementation

• HL7 Terminology Services for code system management

FHIR-MCP: Built with ❤️ for healthcare interoperability