Epic Patient API MCP Server

Fake Epic MCP server with file-based patient data and LLM-powered search.

Features

• Two-tier data access: List summaries first, then fetch details by ID

• 15 MCP Tools for querying patient data:

  • List tools (return IDs, dates, metadata only): list_patient_allergies, list_patient_medications, list_patient_conditions, list_clinical_notes, list_lab_results, list_vitals, list_procedures

  • Detail tools (require IDs, return full data): get_allergy_details, get_medication_details, get_condition_details, get_clinical_note_details, get_lab_result_details, get_vital_details, get_procedure_details

  • Attachment tool: get_note_attachment

  • Search tool: search_patient_data - Natural language search using LLM

• Pluggable LLM: Supports Gemini or OpenRouter for natural language search

• File-based storage: Patient data in YAML files under patients/

Setup

1. Install: uv pip install -e .

2. Configure LLM in .env:

   • Gemini (default): GEMINI_API_KEY=... (get from https://aistudio.google.com/app/apikey)

   • OpenRouter: LLM_PROVIDER=openrouter, OPENROUTER_API_KEY=..., OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

3. Run: uv run python -m epic_mcp.server

Server runs on http://localhost:8000/sse

Usage Pattern

Two-tier access minimizes data transfer:

1. List to see what's available (IDs + metadata):

   {"patient_id": "patient_001"}

   Returns: [{"id": "allergy-1", "allergen": "Penicillin", "severity": "severe", "recorded_date": "2015-03-20"}]

2. Get details for specific items:

   {"patient_id": "patient_001", "allergy_id": "allergy-1"}

   Returns: {"id": "allergy-1", "allergen": "Penicillin", "reaction": "Hives, difficulty breathing", "severity": "severe", "recorded_date": "2015-03-20"}

Claude Desktop Setup

1. Run server: uv run python -m epic_mcp.server

2. Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   {"mcpServers": {"epic-patient-api": {"url": "http://localhost:8000/sse"}}}

3. Restart Claude Desktop

Available Patients

• patient_001 - John Doe (58M) - Hypertension, Type 2 Diabetes

• patient_002 - Jane Smith (32F) - Hypothyroidism, Pregnant

• patient_003 - Robert Chen (56M) - Stage IV Colorectal Cancer