Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@openemr-mcp Check for drug interactions in Jane Doe's medication list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server for OpenEMR — connect any MCP-compatible AI assistant (Claude Desktop, Cursor, VS Code Copilot) directly to your OpenEMR instance.
17 MCP tools covering:
Category | Tools |
Patients |
|
Appointments |
|
Medications |
|
Providers |
|
FDA Safety |
|
Symptom Lookup |
|
Drug Safety Flags |
|
Clinical Trends |
|
Health Trajectory |
|
Visit Prep |
|
All tools work in mock mode out of the box — no OpenEMR installation required for evaluation.
Related MCP server: FHIR MCP Server
pip install openemr-mcp
# or with uv:
uv add openemr-mcp# Mock mode — no OpenEMR needed
OPENEMR_DATA_SOURCE=mock openemr-mcp
# Against a live OpenEMR FHIR API
OPENEMR_DATA_SOURCE=api \
OPENEMR_API_BASE_URL=https://your-openemr/apis/default \
OPENEMR_OAUTH_SITE=default \
OPENEMR_OAUTH_CLIENT_ID=... \
OPENEMR_OAUTH_CLIENT_SECRET=... \
OPENEMR_OAUTH_USERNAME=admin \
OPENEMR_OAUTH_PASSWORD=... \
openemr-mcpAdd to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"openemr": {
"command": "uvx",
"args": ["openemr-mcp"],
"env": {
"OPENEMR_DATA_SOURCE": "api",
"OPENEMR_API_BASE_URL": "https://your-openemr.example.com/apis/default",
"OPENEMR_OAUTH_SITE": "default",
"OPENEMR_OAUTH_CLIENT_ID": "your_client_id",
"OPENEMR_OAUTH_CLIENT_SECRET": "your_client_secret",
"OPENEMR_OAUTH_USERNAME": "admin",
"OPENEMR_OAUTH_PASSWORD": "your_password"
}
}
}
}For mock mode (demo / evaluation):
{
"mcpServers": {
"openemr": {
"command": "uvx",
"args": ["openemr-mcp"],
"env": {
"OPENEMR_DATA_SOURCE": "mock"
}
}
}
}OPENEMR_DATA_SOURCE)Value | Description |
| Built-in curated demo data — 24 patients, no network required |
| Direct MySQL connection to OpenEMR database |
| OpenEMR FHIR R4 REST API (recommended for production) |
DRUG_INTERACTION_SOURCE)Value | Description |
| 10 built-in drug pairs — always works, no network |
| OpenFDA FAERS co-reporting heuristic — free, no API key required. Severity based on co-report volume (HIGH ≥ 50, MODERATE ≥ 5). Note: Co-reporting indicates correlation, not definitive causation. |
| ⚠️ DEPRECATED/UNAVAILABLE — RxNorm interaction API endpoints retired (returns 404) |
SYMPTOM_SOURCE)Value | Description |
| Curated local dataset — 10 clinical groups |
| Infermedica Symptom Checker API (register here) — free tier 100 calls/day |
OPENFDA_SOURCE)Value | Description |
| Built-in mock data for 6 common drugs |
| Live OpenFDA API — free, optional key for higher rate limits |
See .env.example for the full list with comments.
Key variables:
# Data source
OPENEMR_DATA_SOURCE=mock # mock | db | api
# MySQL (when OPENEMR_DATA_SOURCE=db)
OPENEMR_DB_HOST=localhost
OPENEMR_DB_PORT=3306
OPENEMR_DB_USER=openemr
OPENEMR_DB_PASSWORD=openemr
OPENEMR_DB_NAME=openemr
# FHIR API (when OPENEMR_DATA_SOURCE=api)
OPENEMR_API_BASE_URL=https://your-openemr/apis/default
OPENEMR_OAUTH_SITE=default
OPENEMR_OAUTH_CLIENT_ID=...
OPENEMR_OAUTH_CLIENT_SECRET=...
OPENEMR_OAUTH_USERNAME=admin
OPENEMR_OAUTH_PASSWORD=...
# Optional external APIs
DRUG_INTERACTION_SOURCE=mock # mock | openfda | rxnorm (deprecated)
SYMPTOM_SOURCE=mock # mock | infermedica
INFERMEDICA_APP_ID=
INFERMEDICA_APP_KEY=
OPENFDA_SOURCE=mock # mock | live
OPENFDA_API_KEY=openemr_patient_searchSearch patients by name. Returns patient ID, DOB, sex, city.
{ "query": "Jane" }openemr_appointment_listList upcoming appointments for a patient.
{ "patient_id": "p001" }openemr_medication_listReturn the current medication list for a patient.
{ "patient_id": "p001" }openemr_drug_interaction_checkCheck a list of medications for known drug-drug interactions.
{ "medications": ["warfarin", "aspirin", "metformin"] }openemr_provider_searchSearch healthcare providers by specialty and/or location.
{ "specialty": "Cardiology", "location": "Boston" }openemr_fda_adverse_eventsQuery FDA FAERS database for adverse event reports on a drug.
{ "drug_name": "metformin", "limit": 5 }openemr_fda_drug_labelRetrieve official FDA drug label including boxed warnings and contraindications.
{ "drug_name": "warfarin" }openemr_symptom_lookupLook up possible conditions for a list of symptoms.
{ "symptoms": ["chest pain", "shortness of breath"] }openemr_drug_safety_flag_createCreate a drug safety flag for a patient.
{
"patient_id": "p001",
"drug_name": "warfarin",
"description": "Patient reported unusual bruising",
"flag_type": "adverse_event",
"severity": "HIGH"
}openemr_drug_safety_flag_listList all drug safety flags for a patient.
{ "patient_id": "p001", "status_filter": "active" }openemr_drug_safety_flag_updateUpdate a drug safety flag's severity, description, or status.
{ "flag_id": "uuid-...", "severity": "MODERATE", "status": "resolved" }openemr_drug_safety_flag_deleteDelete a drug safety flag by ID.
{ "flag_id": "uuid-..." }openemr_lab_trendsReturn longitudinal lab trajectories (A1c, LDL, eGFR).
{ "patient_id": "p001", "metrics": ["a1c", "ldl"], "window_months": 24 }openemr_vital_trendsReturn longitudinal vital sign trajectories (weight, BP).
{ "patient_id": "p001", "metrics": ["weight", "bp_systolic", "bp_diastolic"] }openemr_questionnaire_trendsReturn longitudinal questionnaire score trajectories (PHQ-9).
{ "patient_id": "p001", "instrument": "PHQ-9", "window_months": 24 }openemr_health_trajectoryAggregate all metric trajectories and compute clinical drift alerts.
{ "patient_id": "p001", "window_months": 24 }openemr_visit_prepGenerate a pre-visit clinical brief: top risks, medication safety, care gaps, and suggested agenda.
{ "patient_id": "p001", "window_months": 24 }# Clone and install in editable mode
git clone https://github.com/shruti-jn/openemr-mcp
cd openemr-mcp
pip install -e ".[dev]"
# Run tests (mock mode, no external dependencies)
pytest
# Start server locally
OPENEMR_DATA_SOURCE=mock openemr-mcpsrc/openemr_mcp/
├── server.py # MCP server — registers all 17 tools
├── config.py # Pydantic-settings configuration
├── schemas.py # All Pydantic response schemas
├── auth.py # OpenEMR OAuth2 token manager
├── data_source.py # Data source resolver
├── tools/ # 13 tool modules (17 MCP tools)
├── repositories/ # Data access (MySQL, FHIR R4, SQLite)
└── services/ # Business logic (OpenFDA, trajectory alerts, visit prep)Drug safety flags are persisted in a local SQLite database at ~/.openemr_mcp/drug_safety_flags.db.
MIT — see LICENSE.
Pull requests welcome. Please open an issue first for major changes.
This project is part of the AgentForge OpenEMR AI toolkit.
List upcoming appointments for a patient.
Inputs: patient_id (required).
Check a list of medications for known drug-drug interactions. Returns severity-classified interactions.
Inputs: medications (required).
Create a drug safety flag for a patient (adverse event, recall, warning, contraindication, or custom note).
Inputs: patient_id (required), drug_name (required), description (required), flag_type, +2 more.
Delete a drug safety flag by ID.
Inputs: flag_id (required).
List all drug safety flags for a patient, optionally filtered by status.
Inputs: patient_id (required), status_filter.
Update a drug safety flag's severity, description, or status.
Inputs: flag_id (required), severity, description, status.
Query FDA FAERS database for adverse event reports on a drug.
Inputs: drug_name (required), limit.
Retrieve official FDA drug label including boxed warnings, contraindications, and indications.
Inputs: drug_name (required).
Aggregate all metric trajectories (labs, vitals, questionnaires) and compute clinical drift alerts for a patient.
Inputs: patient_id (required), window_months, metrics.
Return longitudinal lab trajectories for a patient (A1c, LDL, eGFR).
Inputs: patient_id (required), metrics, window_months.
Return the current medication list for a patient.
Inputs: patient_id (required).
Search OpenEMR patients by name. Returns matching patient records with ID, DOB, sex, and city.
Inputs: query (required).
Search for healthcare providers by specialty and/or location.
Inputs: specialty, location.
Return longitudinal questionnaire score trajectories for a patient (PHQ-9 depression screening).
Inputs: patient_id (required), instrument, window_months.
Look up possible conditions for a list of symptoms. Returns ranked conditions with urgency level and medical disclaimer.
Inputs: symptoms (required).
Generate a pre-visit clinical brief for a patient: top risks, medication safety, care gaps, and suggested agenda. Evidence-linked, no hallucination.
Inputs: patient_id (required), window_months.
Return longitudinal vital sign trajectories for a patient (weight, BP systolic/diastolic).
Inputs: patient_id (required), metrics, window_months.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 17 tools
Most tools target clearly distinct resources: patient lookup, medications, appointments, drug label/adverse events, symptom lookup, and safety flag CRUD. The only mild overlap is between health_trajectory and the three specific trend tools, but their descriptions make the aggregate-vs-specific distinction clear enough for a capable agent.
Naming is inconsistent: CRUD operations use an object_action pattern (drug_safety_flag_create, drug_safety_flag_update) while most reads use noun phrases like medication_list, provider_search, and vital_trends. All names share the openemr_ prefix and snake_case, but the placement of the action is not predictable across the toolset.
17 tools is slightly above the typical 3-15 range, but the count is defensible for a clinical workflow server that combines EHR data, FDA lookups, and medication safety. Each tool covers a distinct resource or operation, so none feel like filler.
The toolset forms a coherent clinical pre-visit and drug-safety workflow: patient search, medication/appointment review, interaction checks, symptom lookup, trend tracking, and visit prep. Gaps like patient creation or appointment scheduling exist, but the apparent focus on read-side analysis and safety flagging is well covered.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
