charm

CharmHealth MCP Server exposes a comprehensive set of EHR interaction tools designed for LLMs and MCP clients to work with patient records, encounters, and practice information. The server implements 15 core tools covering encounter management, patient search and records, demographic and administrative data handling, clinical notes, medical history, medication and allergy management, diagnosis tracking, laboratory data, vital signs, file management, recalls and follow-ups, and full appointment and task lifecycles. This enables automated workflows, data retrieval, and coordinated clinical documentation while honoring HIPAA-safety considerations. To connect, deploy a HIPAA-compliant MCP client that speaks MCP to the server end-points and configure authentication against CharmHealth APIs through the provided credentials in your environment file. The server supports both standard MCP transport and, with appropriate adjustments, HTTP transport for client communications.

Typical workflows include: querying patient records to retrieve demographics and problem lists, creating or updating encounters and SOAP notes, recording vital signs and clinical findings, managing medications and allergies with safety checks, generating and storing clinical notes, scheduling appointments, and handling task lifecycles. By leveraging the 15 tools, an LLM can reason over a patient’s history, prompt clinicians for clarifications, and orchestrate care activities across the practice while the MCP server consolidates PHI access under configured authorization and auditing. Ensure your MCP client is HIPAA-compliant and operates under your BAA and data governance policies.

Prerequisites:

• Python 3.13 or higher
• CharmHealth API credentials (sandbox or production)
• uv (recommended) or Python environment capable of running the MCP server
• An MCP client that is HIPAA-compliant or operated under your HIPAA program

Installation steps:

1. Clone the repository

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

2. Install dependencies (uv recommended)

uv sync

If you prefer pip:

pip install -e .

3. Configure environment Create a .env file at the project root (example shown in readme):

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_token_url_here
ENV=dev
COLLECT_METRICS=false

4. Run the server (example using uv)

uv run --directory src mcp_server.py

Or, if using Python directly:

python src/mcp_server.py

5. Verify the server is running and accessible, then configure your HIPAA-compliant MCP client to connect to the server endpoint.

Optional Docker alternative:

• Build and run a container with the required environment variables as shown in the README's Docker examples.

Notes and tips:

• All environment variables must be set before starting the server; missing credentials will prevent startup.
• The server can be run in stdio mode or, with additional configuration, in HTTP transport mode for MCP clients that support HTTP.
• If you plan to use HTTP transport, you will likely need to modify mcp_server.py to enable HTTP transport as described in the Docker deployment section.
• For production deployments, enable ENV=prod and consider enabling OTEL metrics (COLLECT_METRICS=true) and appropriate logging.
• Ensure your MCP client and any LLM services are covered by a signed BAA and that data retention policies, encryption in transit, and access controls align with HIPAA requirements.
• If you encounter issues starting the server, verify that the CharmHealth API credentials are valid and that the base URL points to the correct environment (sandbox vs production).