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

```bash
npm install -g mychart-mcp-server
npx playwright install chromium
```

Or from source:

```bash
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

```json
{
  "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

1. `mychart_set_provider` with your portal URL (e.g. `https://mychart.example-health.org/MyChart`)
2. `mychart_login` → sign in + MFA in the window that opens (check "Remember this device")
3. `mychart_list_test_results` → returns `r1, r2, ...`
4. `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