MyChart MCP Server
An MCP (Model Context Protocol) server that connects to any Epic MyChart patient portal to log in, list your test results, and download them as PDFs — so an AI assistant can help you understand your own lab work.
Epic offers no simple public login API (the official FHIR route requires per-organization app registration), so this server drives the MyChart website with Playwright:
- Login is interactive and private — a visible browser window opens; you type your username/password and complete MFA yourself. Credentials never pass through the AI, the MCP protocol, or this server's tool arguments.
- Session persists — cookies (including MyChart's session-scoped auth cookie) are exported to disk after login and replayed on every launch, so subsequent operations run headless until the portal expires the session server-side.
- Works across MyChart versions — scraping tries the modern SPA routes (
/app/test-results) first, then classic routes, with permissive selectors.
| Tool | Purpose |
|---|
mychart_set_provider | Set your health system's MyChart URL (one-time). Paste any URL from their MyChart site. |
mychart_login | Opens a visible browser window; you sign in + complete MFA there. |
mychart_session_status | Check provider config + whether the saved session is still valid. |
mychart_list_test_results | List ALL test results (auto-expands "Show more"), with ids r1, r2, .... |
mychart_get_test_result | Full readable content of one result (values, ranges, comments). |
mychart_download_test_result | Save a result as PDF to ~/.mychart-mcp/downloads. |
mychart_screenshot | Debug: full-page PNG of what the automation browser sees. |
mychart_close_browser | Close the browser process (session stays saved on disk). |
Installation
npm install -g mychart-mcp-server
npx playwright install chromium
Or from source:
git clone https://github.com/kriskraw80/mychart-mcp-server.git
cd mychart-mcp-server
npm install
npx playwright install chromium
npm run build
Register with Claude Code / Claude Desktop
{
"mcpServers": {
"mychart": {
"command": "npx",
"args": ["mychart-mcp-server"]
}
}
}
(Or point command at node with args: ["<path>/dist/index.js"] for a source checkout.) Restart your MCP client after config changes.
Optional environment variables
| Variable | Purpose |
|---|
MYCHART_URL | Default provider URL (alternative to mychart_set_provider). |
MYCHART_USERNAME / MYCHART_PASSWORD | If set on the server process, the login form is pre-filled (MFA is still completed by you in the window). Optional — typing in the window is the default and safest. |
Typical flow
mychart_set_provider with your portal URL (e.g. https://mychart.example-health.org/MyChart)mychart_login → sign in + MFA in the window that opens (check "Remember this device")mychart_list_test_results → returns r1, r2, ...mychart_get_test_result r1 or mychart_download_test_result r1
Data locations
Everything lives in ~/.mychart-mcp/ — keep it out of synced folders (the Chromium profile does not tolerate file sync):
config.json — provider URLbrowser-profile/ — persistent Chromium profilestorage-state.json — exported session cookies (replayed on each launch)results-cache.json — id → result-URL map from the last list calldownloads/ — PDFs and screenshots
Notes & limitations
- Personal use, no warranty. This tool automates the MyChart web portal to access your own health records — a right you have under HIPAA — but portal scraping is not officially sanctioned by Epic. Use at your own discretion.
- MyChart's DOM varies by health system and Epic version. If listing finds nothing, use
mychart_screenshot to see the rendered page; selectors may need a tweak for your provider. Some systems host MyChart on non-obvious domains (e.g. secure.<org>.org rather than mychart.<org>.org) — paste the URL straight from your browser.
- The server prefers your system-installed Chrome (then Edge, then Playwright's bundled Chromium) — real Chrome's app-bound cookie encryption requires the whole profile to stay on one browser brand, and some Windows machines can't run the bundled build.
- PDF download renders the result detail page via headless Chrome (
page.pdf), which is version-independent, rather than hunting for per-version "Download" buttons.
- Sessions expire server-side after idle time; just run
mychart_login again.
login-helper.mjs, run-direct.mjs, and run-batch.mjs drive the built dist/ code directly — handy for re-login or batch fetching without an MCP client in the loop.
License
MIT