FHIR-MCP - FHIR Model Context Protocol Server

TypeScript Node.js License

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 install
Build the project:
npm run build
Configure 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 start
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

packages/ ├── mcp-fhir-server/ # Main MCP server implementation │ ├── src/ │ │ ├── providers/ # FHIR and terminology providers │ │ ├── security/ # PHI guard and audit logging │ │ ├── tools/ # MCP tool handlers and schemas │ │ └── types/ # TypeScript definitions │ └── dist/ # Compiled JavaScript (ES modules) ├── examples/ │ └── http-bridge/ # HTTP REST API bridge for web clients │ docs/ ├── QUICKSTART.md # Getting started guide ├── PROMPTS.md # LLM prompt library ├── SECURITY.md # Security and privacy guide └── AI_INTEGRATION.md # AI assistant integration examples tests/ ├── e2e/ # End-to-end tests └── QA-REPORT.md # Comprehensive QA test results

🔒 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:

# Build the project first npm run build # Full QA test suite (comprehensive function testing) node manual-qa-test.js # E2E integration tests node tests/e2e/test-fhir-mcp.js # Type checking npm run typecheck # Linting (with improved type safety) npm run lint

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_BASE_URL`	FHIR server base URL	`https://hapi.fhir.org/baseR4`
`FHIR_TOKEN`	Bearer token for FHIR server	-
`TERMINOLOGY_BASE_URL`	HL7 terminology service URL	`https://tx.fhir.org/r4`
`TERMINOLOGY_TOKEN`	Bearer token for terminology service	-
`PHI_MODE`	PHI protection mode ( `safe` or `trusted` )	`safe`
`ENABLE_AUDIT`	Enable audit logging	`true`

🤖 Using with Claude

Add FHIR-MCP to your Claude MCP configuration:

{ "mcpServers": { "fhir": { "command": "node", "args": ["path/to/FHIR-MCP/packages/mcp-fhir-server/dist/index.js"], "env": { "FHIR_BASE_URL": "https://your-fhir-server.com/fhir", "TERMINOLOGY_BASE_URL": "https://tx.fhir.org/r4", "PHI_MODE": "safe", "ENABLE_AUDIT": "true" } } } }

🌐 HTTP Bridge for Web Applications

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

Local Development

# Build the HTTP bridge first cd packages/examples/http-bridge npm run build # Start the HTTP bridge server PORT=3001 FHIR_BASE_URL="https://hapi.fhir.org/baseR4" TERMINOLOGY_BASE_URL="https://tx.fhir.org/r4" PHI_MODE="safe" ENABLE_AUDIT="true" npm start

Docker Deployment (Recommended)

# Build and start with Docker Compose docker-compose up --build # Or run individual commands docker build -t fhir-mcp . docker run -p 3002:3001 -e FHIR_BASE_URL="https://hapi.fhir.org/baseR4" -e TERMINOLOGY_BASE_URL="https://tx.fhir.org/r4" -e PHI_MODE="safe" -e ENABLE_AUDIT="true" fhir-mcp

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

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

FhirMCP