CharmHealth MCP Server

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

What is an MCP Server?

MCP Info

Attribute	Details
Docker Image	mcp/charmhealth-mcp-server
Author	CharmHealth
Repository	https://github.com/CharmHealth/charm-mcp-server

Image Building Info

Attribute	Details
Dockerfile	https://github.com/CharmHealth/charm-mcp-server/blob/b605438d97c13536295f8dbab17afb0e1e269548/Dockerfile
Commit	b605438d97c13536295f8dbab17afb0e1e269548
Docker Image built by	Docker Inc.
Docker Scout Health Score
Verify Signature	COSIGN_REPOSITORY=mcp/signatures cosign verify mcp/charmhealth-mcp-server --key https://raw.githubusercontent.com/docker/keyring/refs/heads/main/public/mcp/latest.pub
Licence	MIT License

Available Tools (14)

Tools provided by this Server	Short Description
findPatients	Find patients.
getPracticeInfo	Get practice information.
manageAppointments	Manage appointments.
manageEncounter	Manage encounters.
managePatient	Manage patients.
managePatientAllergies	Manage patient allergies.
managePatientDiagnoses	Manage patient diagnoses.
managePatientDrugs	Manage patient drugs and supplements.
managePatientFiles	Manage patient files and documents.
managePatientLabs	Manage patient laboratory results.
managePatientNotes	Manage patient notes.
managePatientRecalls	Manage patient recalls.
managePatientVitals	Manage patient vitals and vital signs.
reviewPatientHistory	Review patient history.

---

Tools Details

Tool: findPatients

Find patients.

Find patients quickly using natural search terms or specific criteria. Handles everything from "find John Smith" to complex searches like "elderly diabetes patients in California". Essential first step for any patient-related task.

Quick searches: Use search_type="name" with query="John Smith" for basic name searches Phone lookups: Use search_type="phone" with query="555-1234" (handles any format) Medical record: Use search_type="record_id" with query="MR123456"

Complex searches: Use search_type="advanced" with multiple criteria:

• Age ranges: age_min=65, age_max=80 for elderly patients
• Location: state="CA", city="Los Angeles" for geographic filtering
• Medical: blood_group="O+", language="Spanish" for clinical needs

Always returns patient_id needed for other tools. Start here before any patient operations.

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
age_max	string optional
age_min	string optional
blood_group	string optional
category_id	string optional
city	string optional
country	string optional
created_after	string optional
created_before	string optional
facility_id	string optional
gender	string optional
has_phr_account	string optional
language	string optional
limit	string optional
marital_status	string optional
modified_after	string optional
modified_before	string optional
page	string optional
postal_code	string optional
query	string optional
search_type	string optional
sort_by	string optional
sort_order	string optional
state	string optional
status	string optional

---

Tool: getPracticeInfo

Get practice information.

Get essential practice information needed for other operations - available facilities, providers, vital signs templates, etc. Use this to understand practice setup and get IDs for other tools.

• "facilities": List all practice locations with IDs needed for scheduling
• "providers": List all providers with IDs needed for appointments and encounters
• "vitals": Available vital sign templates for documentation
• "overview": Summary of practice setup with key counts and recent activity

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
info_type	string optional

---

Tool: manageAppointments

Manage appointments.

Complete appointment lifecycle management - schedule new appointments, reschedule existing ones, cancel appointments, and list appointments with flexible filtering. Handles the full appointment workflow.

Actions:

• "schedule": Create new appointment (requires patient_id, provider_id, facility_id, appointment_date, appointment_time). Check the provider's availability with manageAppointments(action='list') and provider_id, and across all facilities for the provider before suggesting a time.
• "reschedule": Change existing appointment time (requires appointment_id + new scheduling details)
• "cancel": Cancel appointment (requires appointment_id + cancel_reason)
• "list": Show appointments with filtering (requires start_date, end_date_range, facility_ids)

Time format: Use 12-hour format like "09:30 AM" or "02:15 PM" For recurring: Set repetition to "Weekly" or "Daily" and provide frequency + end_date For double booking: Use provider_double_booking="allow" or resource_double_booking="allow" to override checks For cancellation: Use delete_type "Current" for single appointment or "Entire" for recurring series

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
appointment_date	string optional
appointment_id	string optional
appointment_time	string optional
cancel_reason	string optional
consent_forms	string optional
delete_type	string optional
duration_minutes	string optional
end_date	string optional
end_date_range	string optional
facility_id	string optional
facility_ids	string optional
frequency	string optional
member_ids	string optional
message_to_patient	string optional
mode	string optional
patient_id	string optional
provider_double_booking	string optional
provider_id	string optional
questionnaire	string optional
reason	string optional
receipt_id	string optional
repetition	string optional
resource_double_booking	string optional
resource_id	string optional
start_date	string optional
status	string optional
status_ids	string optional
visit_type_id	string optional
weekly_days	string optional

---

Tool: manageEncounter

Manage encounters.

Complete encounter workflow - create, review, and sign encounters with comprehensive clinical documentation. Essential for clinical workflow from initial documentation through final signature.

Actions:

• "create": Create new encounter and document clinical findings (default)
• "review": Display complete encounter details for review before signing
• "sign": Electronically sign encounter after review and confirmation
• "unlock": Unlock a previously signed encounter to allow modifications

For creating encounters:

• Requires: patient_id, provider_id, facility_id, encounter_date
• Optional: appointment_id (to create from existing appointment), visit_type_id, encounter_mode, chief_complaint

For reviewing encounters:

• Requires: patient_id, encounter_id
• Shows comprehensive encounter details including vitals, diagnoses, medications, notes

For signing encounters:

• Requires: patient_id, encounter_id
• Only use after reviewing and confirming all information is accurate

For unlocking encounters:

• Requires: patient_id, encounter_id, reason
• Used to unlock signed encounters when modifications are needed
• Must provide a valid reason for unlocking the encounter

Recommended workflow:

1. Create encounter: manageEncounter(patient_id, provider_id, facility_id, encounter_date, action="create")
2. Add clinical data using managePatientVitals(), managePatientDrugs(), managePatientDiagnoses()
3. Review before signing: manageEncounter(patient_id, encounter_id, action="review")
4. Sign to finalize: manageEncounter(patient_id, encounter_id, action="sign")
5. If modifications needed: manageEncounter(patient_id, encounter_id, reason="reason for changes", action="unlock")

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
patient_id	string
action	string optional
appointment_id	string optional
chief_complaint	string optional
encounter_date	string optional
encounter_id	string optional
encounter_mode	string optional
facility_id	string optional
provider_id	string optional
reason	string optional
visit_type_id	string optional

---

Tool: managePatient

Manage patients.

Complete patient management with comprehensive demographic, social, and administrative data. Handles patient creation, updates, status changes, and complex relationships. Supports all CharmHealth patient data fields for complete EHR functionality.

Actions:

• "create": Add new patient (requires first_name, last_name, gender, date_of_birth OR age, facility_ids)
• "update": Modify existing patient (requires patient_id + fields to change).
• "activate": Reactivate deactivated patient (requires patient_id only)
• "deactivate": Deactivate patient (requires patient_id only)

Update Modes:

• update_specific_details=True: Only updates the fields you provide, preserves all other existing data (RECOMMENDED, Default)
• update_specific_details=False: Complete record update - must provide all fields or existing data will be lost

Demographics: Supports comprehensive patient information including social history, family data Addresses: If any address field provided, country is required (defaults to US) Facilities: Pass as list of facility IDs like "facility_123,facility_456". Categories: Pass as list like [{"category_id": "category_123"}]

Complex Relationships:

• caregivers: [{"first_name": str, "last_name": str, "relationship": str, "contact": {...}, "address": {...}}]
• guarantor: [{"first_name": str, "last_name": str, "relationship": str, "contact": {...}, "address": {...}}]
• id_qualifiers: [{"id_qualifier": 1-8 or 99, "id_of_patient": "ID_value"}]

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
address_line1	string optional
address_line2	string optional
age	string optional
area	string optional
birth_order	string optional
blood_group	string optional
caregivers	string optional
categories	string optional	Categories: Pass as list like [{"category_id": "category_123"}]
cause_of_death	string optional
city	string optional
country	string optional
county_code	string optional
custom_field_1	string optional
custom_field_2	string optional
custom_field_3	string optional
custom_field_4	string optional
custom_field_5	string optional
date_of_birth	string optional
deceased	string optional
district	string optional
dod	string optional
duplicate_check	string optional
email	string optional
email_notification	string optional
emergency_contact_name	string optional
emergency_contact_phone	string optional
emergency_extn	string optional
employment_status	string optional
ethnicity	string optional
facility_ids	string optional
first_name	string optional
gender	string optional
gender_identity	string optional
guarantor	string optional
home_phone	string optional
id_qualifiers	string optional
introduction	string optional
is_multiple_birth	string optional
language	string optional
last_name	string optional
linked_patient_id	string optional
maiden_name	string optional
marital_status	string optional
middle_name	string optional
mother_first_name	string optional
mother_last_name	string optional
nick_name	string optional
patient_id	string optional
payment_end_date	string optional
payment_source	string optional
payment_start_date	string optional
phone	string optional
post_box	string optional
preferred_communication	string optional
primary_phone	string optional
race	string optional
record_id	string optional
rep_first_name	string optional
rep_last_name	string optional
send_phr_invite	string optional
sexual_orientation	string optional
smoking_status	string optional
source_name	string optional
source_value	string optional
state	string optional
suffix	string optional
text_notification	string optional
update_specific_details	string optional
voice_notification	string optional
work_phone	string optional
work_phone_extn	string optional
zip_code	string optional

---

Tool: managePatientAllergies

Manage patient allergies.

Critical allergy management with safety alerts - document patient allergies, update allergy information, and maintain allergy safety checks. Essential for safe prescribing and clinical decision-making.

Actions:

• "add": Document new allergy (requires allergen, allergy_type, severity, reactions, allergy_date)
• "list": Show all patient allergies (requires only patient_id)
• "update": Modify existing allergy (requires record_id + fields to change)
• "delete": Remove allergy record (requires record_id)

Safety critical: Always check allergies before prescribing medications. Common allergens: "Penicillin", "Latex", "Shellfish", "Nuts", "Contrast dye" Severity levels: "Mild", "Moderate", "Severe", "Life-threatening"

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
patient_id	string
allergen	string optional
allergy_date	string optional
allergy_status	string optional
allergy_type	string optional
comments	string optional
reactions	string optional
record_id	string optional
severity	string optional

---

Tool: managePatientDiagnoses

Manage patient diagnoses.

Complete diagnosis management for patient problem lists - add new diagnoses, update existing conditions, and maintain accurate medical problem lists. Essential for clinical reasoning and care planning.

Actions:

• "add": Add new diagnosis (requires diagnosis_name, diagnosis_code, code_type)
• "list": Show all patient diagnoses (optionally filter by encounter_id)
• "update": Modify existing diagnosis (requires record_id + fields to change)
• "delete": Remove diagnosis (requires record_id). Ask the user if they are sure they want to delete the diagnosis before proceeding.

Code types: "ICD10", "SNOMED" Status options: "Active", "Inactive", "Resolved" Use encounter_id to link diagnosis to specific visit for billing and documentation

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
patient_id	string
code_type	string optional
comments	string optional
diagnosis_code	string optional
diagnosis_name	string optional
diagnosis_order	string optional
diagnosis_status	string optional
encounter_id	string optional
from_date	string optional
record_id	string optional
to_date	string optional

---

Tool: managePatientDrugs

Manage patient drugs and supplements.

Unified drug management for medications, supplements, and vitamins - prescribe medications, document supplements, manage drug interactions. Includes automatic allergy checking and comprehensive drug safety workflow for optimal patient care.

Actions:

• "add": Prescribe new drug (requires drug_name, directions for medications; drug_name, dosage for supplements)
• "update": Modify existing prescription (requires record_id + fields to change)
• "discontinue": Stop drug (requires record_id)
• "list": Show all patient drugs by type (optionally filter by substance_type)

Substance Types:

• "medication": Prescription drugs (requires directions, refills)
• "supplement": OTC supplements/vitamins (requires dosage as integer)
• "vitamin": Specific vitamins (requires dosage as integer)

Safety: Automatically checks allergies before prescribing unless check_allergies=False For medications: Use clear directions like "Take 1 tablet by mouth twice daily with food" For supplements: Provide dosage as integer (e.g., 5) and use strength for units (e.g., "500mg")

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
patient_id	string
check_allergies	string optional
comments	string optional
directions	string optional
dosage	string optional
dosage_unit	string optional
dose_form	string optional
drug_name	string optional
encounter_id	string optional
end_date	string optional
frequency	string optional
intake_type	string optional
quantity	string optional
record_id	string optional
refills	string optional
route	string optional
start_date	string optional
status	string optional
strength	string optional
substance_type	string optional
weaning_schedule	string optional

---

Tool: managePatientFiles

Manage patient files and documents.

Patient file and document management - upload patient photos, manage identity documents, and send PHR (Personal Health Record) invitations. Handles the complete patient file workflow.

Actions:

• "upload_photo": Upload patient photo (requires photo_file path)
• "delete_photo": Remove patient photo (requires only patient_id)
• "upload_id": Upload identity document (requires id_file, id_qualifier)
• "send_phr_invite": Send PHR portal invitation (requires email)

ID Qualifiers: military_id, state_issued_id, drivers_license_id, passport_id, social_security_number, etc. File paths should be absolute paths to image/PDF files on the system.

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
patient_id	string
email	string optional
id_file	string optional
id_of_patient	string optional
id_qualifier	string optional
photo_file	string optional
rep_first_name	string optional
rep_last_name	string optional

---

Tool: managePatientLabs

Manage patient laboratory results.

Complete laboratory results management - list lab results, get detailed reports, and add new lab results. Handles the full lab workflow for clinical decision-making.

Actions:

• "list": Show lab results with filtering (optionally filter by patient_id, reviewer_id, status)
• "get_details": Get detailed lab report (requires group_id OR lab_order_id)
• "add_result": Add new lab results (requires patient_id + result_details)

For detailed results: Use group_id for result groups or lab_order_id for specific orders For adding results: Provide structured result_details with tests, parameters, and values Status codes: 0 for pending, 2 for final results

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
group_id	string optional
is_ascending	string optional
lab_order_id	string optional
no_of_records	string optional
patient_id	string optional
result_details	string optional
reviewer_id	string optional
sort_by	string optional
start_index	string optional
status	string optional

---

Tool: managePatientNotes

Manage patient notes.

Quick clinical note management for important patient information - add care notes, provider communications, and clinical observations that need to be highlighted across all patient interactions.

Actions:

• "add": Add new clinical note (requires notes content)
• "list": Show all patient notes (requires only patient_id)
• "update": Modify existing note (requires record_id + notes content)
• "delete": Remove note (requires record_id). Ask the user if they are sure they want to delete the note before proceeding.

Use for: Important care instructions, provider alerts, patient preferences, social determinants Formal encounter notes should use manageEncounter() instead

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
patient_id	string
notes	string optional
record_id	string optional

---

Tool: managePatientRecalls

Manage patient recalls.

Patient recall and follow-up management - schedule preventive care reminders, follow-up appointments, and care plan reminders. Ensures patients receive timely care according to clinical guidelines.

Actions:

• "add": Schedule new recall (requires recall_type, notes, provider_id, facility_id)
• "list": Show all patient recalls (requires only patient_id)
• "update": Modify existing recall (requires record_id + fields to change)
• "delete": Remove recall (requires record_id). Ask the user if they are sure they want to delete the recall before proceeding.

Common recall types: "Annual Physical", "Mammogram", "Colonoscopy", "Lab Follow-up", "Medication Review" Reminder timing: email_reminder_before/text_reminder_before in days (e.g., 7 for one week) Use getPracticeInfo() to get valid provider_id and facility_id values

When required parameters are missing, ask the user to provide the specific values rather than proceeding with defaults or auto-generated values.

Parameters	Type	Description
action	string
patient_id	string
email_reminder_before	string optional
encounter_id	string optional
facility_id	string optional
notes	string optional
provider_id	string optional
recall_date	string optional
recall_period	string optional
recall_time	string optional
recall_timeunit	string optional
recall_type	string optional
record_id	string optional
send_email_reminder	string optional
send_text_reminder	string optional
text_reminder_before	string optional

---

Tool: managePatientVitals

Manage patient vitals and vital signs.

Complete patient vital signs management - record vitals during encounters, review vital trends, update incorrect readings, and track patient health metrics over time. Essential for clinical monitoring.

Actions:

• "add": Record new vitals (requires patient_id + encounter_id + vitals dict OR individual vital fields). Check available vitals with getPracticeInfo(info_type='vitals') first to ensure all vital names and units are correct.
• "list": Show patient vital history (optionally filter by date range)
• "update": Modify existing vital record (requires record_id + fields to change)
• "delete": Remove incorrect vital record (requires record_id)

Vitals Format:

• As dict: {"Weight": "70 kg", "BP": "120/80 mmHg", "Pulse": "72 bpm", "Temperature": "98.6 F"}
• Ind

[...]