epic-ehr-mcp-server by pcjx8 - MCP Server

EPIC-Style EHR MCP Server

A comprehensive Electronic Health Record (EHR) system implementing EPIC-style workflows with WebSocket support, JWT authentication, and complete healthcare data management.

🏥 Overview

This is a production-ready Model Context Protocol (MCP) server that simulates a complete EHR system similar to EPIC. It provides 20+ healthcare tools for managing patient data, appointments, medications, lab results, and more.

Perfect for:

Healthcare AI agent development
EHR integration testing
Clinical workflow simulation
Medical AI training
FHIR/HL7 prototyping
Healthcare app development

✨ Features

Complete EHR Functionality

Patient Management - Demographics, search, insurance
Clinical Documentation - Medical history, allergies, SOAP notes, care plans
Medication Management - Prescriptions, refills, current medications
Lab & Diagnostics - Lab results, orders, imaging reports
Vital Signs - Recording and history
Appointments - Scheduling, cancellation, status tracking
Immunizations - Vaccine records
Provider Directory - Search by specialty
Billing & Insurance - Claims, charges

Security Features

JWT Token-based Authentication (industry standard)
Access tokens (24-hour expiry) and refresh tokens (30-day expiry)
Token revocation (logout functionality)
Role-based access control (Doctor, Nurse, Patient, Admin)
Permission validation for sensitive operations
Secure token signing with HS256 algorithm

Technical Features

WebSocket + stdio transport
20+ MCP tools
Comprehensive mock data
Session-based authentication
EPIC-style operations
Production-ready architecture

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/YOUR_USERNAME/epic-ehr-mcp-server.git
cd epic-ehr-mcp-server

# Install dependencies
pip install -r requirements.txt

Run Server

# WebSocket mode (for remote connections)
python ehr_server.py --websocket

# Stdio mode (for local MCP clients like Kiro)
python ehr_server.py

Test

# Run test client
python test_client.py

📚 Documentation

- 5-minute setup guide
- Complete JWT authentication guide
- Cloud deployment options (AWS, Azure, Railway)
- VPS deployment without Docker
- JWT implementation details

🔐 Authentication

Test Users

Username	Password	Role	Description
dr_smith	doctor123	doctor	Dr. Sarah Smith (Internal Medicine)
nurse_jones	nurse123	nurse	Nurse John Jones
patient_doe	patient123	patient	John Doe (Patient MRN001)
admin_user	admin123	admin	System Administrator

Example Usage

import asyncio
import websockets
import json

async def example():
    async with websockets.connect('ws://localhost:8766') as ws:
        # Authenticate
        auth_msg = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "authenticate",
                "arguments": {
                    "username": "dr_smith",
                    "password": "doctor123"
                }
            }
        }
        await ws.send(json.dumps(auth_msg))
        response = await ws.recv()
        auth_data = json.loads(response)
        
        # Extract access token
        access_token = auth_data['result']['content'][0]['text']['access_token']
        
        # Get patient data
        patient_msg = {
            "jsonrpc": "2.0",
            "id": 2,
            "method": "tools/call",
            "params": {
                "name": "get_patient",
                "arguments": {
                    "access_token": access_token,
                    "mrn": "MRN001"
                }
            }
        }
        await ws.send(json.dumps(patient_msg))
        response = await ws.recv()
        print(response)

asyncio.run(example())

🛠️ Available Tools

Authentication

authenticate - Login and get JWT tokens
refresh_token - Refresh expired access token
logout - Revoke access token

Patient Management

get_patient - Get patient demographics
search_patients - Search for patients

Medical Records

get_medical_history - Get conditions and diagnoses
get_allergies - Get patient allergies
get_medications - Get current medications
prescribe_medication - Prescribe new medication

Lab & Diagnostics

get_lab_results - Get lab test results
order_lab_test - Order new lab test
get_imaging_reports - Get imaging reports

Vital Signs

get_vital_signs - Get vital signs history
record_vital_signs - Record new vitals

Appointments

get_appointments - Get patient appointments
schedule_appointment - Schedule new appointment
cancel_appointment - Cancel appointment

Clinical Documentation

get_clinical_notes - Get clinical notes
create_clinical_note - Create new note

Other

get_immunizations - Get immunization history
get_care_plan - Get patient care plan
search_providers - Search healthcare providers
get_billing_info - Get billing information

🏗️ Architecture

Client (AI Agent, Web App, Mobile)
    ↓
WebSocket/Stdio Transport (JSON-RPC 2.0)
    ↓
JWT Authentication & Authorization
    ↓
MCP Server Core (Tool Registry)
    ↓
Business Logic Layer (20+ Tools)
    ↓
Data Layer (Mock Data / Database)

📦 Project Structure

epic-ehr-server/
├── ehr_server.py              # Main MCP server
├── auth.py                    # JWT authentication
├── ehr_tools.py              # Tool implementations
├── mock_data.py              # Healthcare mock data
├── test_client.py            # Test client
├── requirements.txt          # Dependencies
├── README.md                 # This file
├── AUTHENTICATION.md         # Auth guide
├── DEPLOYMENT.md            # Deployment guide
├── SIMPLE_DEPLOYMENT.md     # VPS deployment
├── QUICKSTART.md            # Quick start
└── JWT_FEATURES.md          # JWT details

🚀 Deployment

Quick Deploy (Railway)

Push to GitHub
Connect Railway to GitHub
Railway auto-deploys
Get public URL

VPS Deployment

See for step-by-step guide.

Cloud Deployment

See for AWS, Azure, Google Cloud options.

🔒 Security

JWT token-based authentication
Role-based access control (RBAC)
Token expiration and refresh
Secure password hashing (SHA-256)
HTTPS/WSS support
Input validation
Permission checks

🧪 Testing

# Run complete workflow test
python test_client.py

# Run appointment booking test
python appointment_booking_example.py

# Run persistence test
python test_persistence.py

📊 Mock Data

The server includes comprehensive mock data:

2 patients with complete medical records
Medical history, allergies, medications
Lab results, vital signs, immunizations
Appointments, clinical notes, care plans
2 providers (doctors)
Billing records

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

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

🙏 Acknowledgments

Built with MCP (Model Context Protocol)
Inspired by EPIC EHR workflows
JWT implementation using PyJWT

📞 Support

For issues, questions, or contributions:

Open an issue on GitHub
Check documentation in the repo
Review example files

🗺️ Roadmap

Built with ❤️ for healthcare AI development