How it works¶
In short: download your records once, keep them in a file on your computer, and let an AI assistant read that file. Three separate pieces, and only the first one ever uses the internet.
1. Download 2. Store 3. Ask
MyChart ──Epic's patient API──▶ mychart-mcp sync ──▶ database file ──read-only──▶ AI assistant
(your health system) (on your computer) (on your computer) (you choose)
1. Download: mychart-mcp sync¶
You sign in to MyChart in your normal web browser, on your health system's own sign-in page. mychart-mcp never sees your password. MyChart asks whether to let the app read your records; you approve, and the download starts.
- What's downloaded: conditions and diagnoses, lab results and vital signs, visit notes (including their full text), medications, allergies, immunizations, procedures, reports and visits.
- First time: the whole chart. A large chart with thousands of notes takes several minutes.
- After that: only what changed since last time, which is much quicker. Once a month it downloads everything again to catch records your health system removed.
- When: whenever you run it, for example after a visit or once a month. It doesn't run on its own.
2. Store: one file on your computer¶
Records go into a single database file in your user folder that only your account can read. Nothing is uploaded anywhere. Delete the file and they're gone.
3. Ask: mychart-mcp serve¶
Your AI assistant starts this part. It answers the assistant's lookups, like "find lab results for A1c" or "show this note", from the database file. It opens the file read-only and never connects to the internet.
What happens to the answers depends on the assistant: a model running on your computer keeps everything local; a hosted one receives the records it uses. See Privacy & security.
Without an Epic app: Apple Health¶
If your health system is connected to the Health app on your iPhone, you can export
everything from Health and import that file instead (mychart-mcp import). It's a quick way
to try mychart-mcp, but Apple's export doesn't include the text of visit notes. Direct
download is the recommended way. See Getting started.
Technical details¶
- Standards: the download is a SMART on FHIR standalone patient launch against your
health system's Epic FHIR R4 API: a public client using PKCE, read-only
patient/*.readscopes, and a one-shot redirect listener on127.0.0.1. The access token stays in memory for that run only. - Incremental syncs: each sync records a restart point per FHIR server. Later runs read
the server's CapabilityStatement and search labs, reports, notes and encounters with
_lastUpdated; small types are refetched in full. A full sync runs every 30 days or with--full. Keeping it current has the details. - Storage: SQLite with an FTS5 full-text index over names, codes (ICD-10, SNOMED, LOINC,
…) and note text. The file is created
0600in a0700directory. - Server: an MCP server on stdio. It opens the
database with
mode=roandquery_only, has no write tools, and never imports the network code. Its tools are listed in the Reference.