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
Install dependencies:
npm installBuild the project:
npm run buildConfigure environment:
export FHIR_BASE_URL="https://hapi.fhir.org/baseR4" export TERMINOLOGY_BASE_URL="https://tx.fhir.org/r4" export PHI_MODE="safe"Start the server:
cd packages/mcp-fhir-server npm startTest functionality:
node test-basic-functionality.js
๐ ๏ธ Available Tools
FHIR Operations
fhir.capabilities
- Get server capability statementfhir.search
- Search resources with advanced filteringfhir.read
- Read specific resources by IDfhir.create
- Create new FHIR resourcesfhir.update
- Update existing resources
Terminology Services
terminology.lookup
- Look up code properties and display namesterminology.expand
- Expand ValueSets to get contained codesterminology.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:
Variable | Description | Default |
| FHIR server base URL |
|
| Bearer token for FHIR server | - |
| HL7 terminology service URL |
|
| Bearer token for terminology service | - |
| PHI protection mode (
or
) |
|
| Enable audit logging |
|
๐ค 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 statusGET /tools
- List available toolsPOST /fhir/capabilities
- FHIR server capabilitiesPOST /fhir/search
- Search FHIR resourcesPOST /fhir/read
- Read FHIR resourcesPOST /fhir/create
- Create FHIR resources (write operations)POST /fhir/update
- Update FHIR resources (write operations)POST /terminology/lookup
- Terminology lookupPOST /terminology/expand
- ValueSet expansionPOST /terminology/translate
- Code translationPOST /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
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)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
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables LLMs to securely interact with FHIR healthcare servers and HL7 terminology services. Provides comprehensive healthcare data operations with built-in PHI protection, audit logging, and SMART on FHIR authentication.