mychart-mcp-server

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.

Tools

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 URL
• browser-profile/ — persistent Chromium profile
• storage-state.json — exported session cookies (replayed on each launch)
• results-cache.json — id → result-URL map from the last list call
• downloads/ — 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