fhir-mcp by xSoVx - MCP Server

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

- Installation and basic usage
- Ready-to-use LLM prompts and patterns
- 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 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 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