CharmHealth MCP Server

An MCP server for CharmHealth EHR that allows LLMs and MCP clients to interact with patient records, encounters, and practice information.

Critical HIPAA Notice

[!CAUTION] This server can access, transmit, and surface protected health information (PHI). Use it only with:

• HIPAA-compliant LLM services covered by a signed BAA and configured with no training and zero data retention
• HIPAA-compliant MCP clients, or clients operated entirely within your HIPAA compliance program

If you are using this with actual patient data (non-sandbox data), do not connect non-HIPAA consumer LLM endpoints or clients. You are responsible for enforcing access controls, audit logging, encryption in transit/at rest, and data retention policies for your deployment.

Features

The server provides 15 comprehensive tools for complete EHR functionality:

• Encounter Management: Complete SOAP note workflow and clinical findings
• Patient Search & Records: Advanced patient search with demographics, location, and medical criteria
• Patient Management: Complete demographic and administrative data handling
• Medical History: Comprehensive patient clinical overview and history review
• Drug Management: Unified medications, supplements, and prescribing with safety checks
• Allergy Management: Critical allergy documentation with safety alerts
• Diagnosis Management: Problem list and diagnosis tracking
• Clinical Notes: Quick clinical observations and provider communications
• Recalls & Follow-ups: Preventive care reminders and appointment scheduling
• Vital Signs: Complete vital signs recording and trend monitoring
• File Management: Patient photos, documents, and PHR invitations
• Laboratory Management: Lab results tracking and detailed reporting
• Practice Setup: Facilities, providers, and vital sign templates
• Appointment Management: Complete appointment lifecycle with scheduling and rescheduling
• Task Management: Complete task lifecycle

Quick Start

1. Clone and install dependencies:

   git clone https://github.com/CharmHealth/charm-mcp-server.git
   cd charm-mcp-server
   uv sync
   

2. Configure environment:

   cp .env.example .env  # Create from template if available
   # Edit .env with your CharmHealth API credentials
   

3. Run the server:

   uv run --directory src mcp_server.py
   

4. Configure your HIPAA-compliant MCP client (e.g., an enterprise/HIPAA-compliant deployment of your chosen client) to connect to the server.

Prerequisites

• Python 3.13 or higher
• CharmHealth API credentials (sandbox or production)
• uv to run the server
• An MCP client that is HIPAA-compliant or operated under your HIPAA program
• An LLM service that is HIPAA-compliant and covered by a signed BAA

Installation

1. Clone the Repository

git clone https://github.com/CharmHealth/charm-mcp-server.git
cd charm-mcp-server

2. Install Dependencies

Using uv (recommended):

uv sync

Note: This project uses pyproject.toml for dependency management. If you prefer pip, you can install from the project definition:

pip install -e .

3. Environment Configuration

Create a .env file in the project root with your CharmHealth API credentials:

# CharmHealth API Configuration
CHARMHEALTH_BASE_URL=your_base_uri_here
CHARMHEALTH_API_KEY=your_api_key_here
CHARMHEALTH_REFRESH_TOKEN=your_refresh_token_here
CHARMHEALTH_CLIENT_ID=your_client_id_here
CHARMHEALTH_CLIENT_SECRET=your_client_secret_here
CHARMHEALTH_REDIRECT_URI=your_redirect_uri_here
CHARMHEALTH_TOKEN_URL=your_to

... [View full README on GitHub](https://github.com/CharmHealth/charm-mcp-server#readme)