# KeepMD MCP for EOB Decoder

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that helps an AI assistant read a
medical **Explanation of Benefits (EOB)**, Medicare Summary Notice or itemized bill. It is the same job the
[KeepMD EOB Decoder browser extensions](https://keepmd.org/eob-decoder/) do, exposed to Claude, ChatGPT,
Cursor and any other MCP client.

**Endpoint:** `https://mcp.keepmd.org/eob` (Streamable HTTP, no authentication)
**Documentation:** https://keepmd.org/mcp-eob-decoder/
**Publisher:** KeepMD (VertexMD, Inc.) · support@keepmd.org

**In plain English:** you paste or describe an EOB or bill to Claude, ChatGPT or another assistant, and the
assistant uses this server to say what each code means, what the insurance words mean, whether the amounts add
up, and what to do next. The server only ever sees codes, words and dollar figures.

## What it does

| Tool | Purpose |
| --- | --- |
| `lookup_codes` | Official descriptors for ICD-10-CM diagnosis codes, HCPCS Level II service/supply/drug codes and HCPCS modifiers, with chapter, plain-language notes and licensing notices for CPT, dental, NDC and X12 remark codes (recognized, not described). Up to 50 codes per call. |
| `search_codes` | Find ICD-10-CM or HCPCS Level II codes from words in a description, or by code prefix. |
| `explain_insurance_term` | ~115 insurance and billing terms (allowed amount, coinsurance, CO/PR group codes, No Surprises Act, observation status…) with examples and related terms. |
| `check_eob_math` | Recomputes one service line or claim total from the printed amounts and flags balance billing, mismatched totals and impossible cost sharing. |
| `get_eob_reading_guide` | Step-by-step guide to reading an EOB, disputing a bill, or appealing a denial, with links to official consumer resources. |

Plus the `decode_eob` prompt and two resources (`keepmd://mcp-eob-decoder/glossary`, `keepmd://mcp-eob-decoder/manifest`).

Every tool carries `readOnlyHint: true` and `openWorldHint: false`. Every clinical or financial payload carries a
`disclaimer` field: general billing and coding reference, not medical, legal or financial advice.

## Privacy

The server has no storage and no accounts. Tools accept **codes, terms and dollar amounts only**; no schema takes a
name, date of birth, member ID, claim number or statement text. Tool arguments are never logged. Full policy:
https://keepmd.org/privacy/mcp-eob-decoder/.

## Data

| Set | Release | License |
| --- | --- | --- |
| ICD-10-CM | FY2027 (effective 2026-10-01), NCHS/CMS | Public domain |
| HCPCS Level II | October 2026 quarterly file, CMS | Public domain (CDT D-codes dropped) |
| Glossary, reading guide, plain-language notes | KeepMD-authored | MIT |

CPT (AMA), CDT (ADA) and CARC/RARC (X12) descriptors are licensed and are **not** included. See `NOTICE.md`.
Exact versions and file hashes: `public/data/MANIFEST.json`.

## Use it

**Claude** (claude.ai → Settings → Connectors → Add custom connector): `https://mcp.keepmd.org/eob`
**Claude Code:** `claude mcp add --transport http keepmd-mcp-eob-decoder https://mcp.keepmd.org/eob`
**Cursor / VS Code / other clients:**

```json
{ "mcpServers": { "keepmd-mcp-eob-decoder": { "type": "http", "url": "https://mcp.keepmd.org/eob" } } }
```

**ChatGPT:** install from the app directory once listed (see `chatgpt/`).

Try: *"What do Z00.00, 99213 and J0696 mean on this EOB?"* · *"Explain allowed amount versus billed amount."* ·
*"Billed 1,200, allowed 650, deductible 500, 20% coinsurance. Is my 630 patient responsibility right?"*

## Run it yourself

```bash
npm install --legacy-peer-deps
npm run data:refresh      # downloads the CMS/NCHS releases and rebuilds public/data
npm test && npm run typecheck
npm run dev               # http://localhost:8787/eob
```

## Test it

```bash
npm run dev                                   # terminal 1
npm run smoke -- http://127.0.0.1:8787/eob    # terminal 2: initialize, tools/list, one call per tool, the prompt
npx @modelcontextprotocol/inspector           # point it at http://127.0.0.1:8787/eob (Streamable HTTP)
```

Or add the local server to Claude Code with `claude mcp add --transport http eob-local http://127.0.0.1:8787/eob`
and ask it the reviewer prompts in `docs/SUBMISSIONS.md`. Problems: support@keepmd.org (the issue tracker is off).

Built on `@modelcontextprotocol/server` (`createMcpHandler`, stateless Streamable HTTP) and Cloudflare Workers
with Static Assets for the code sets. Layout, release and data-refresh steps: `CONTRIBUTING.md`, `docs/DEPLOY.md`.
Directory submissions (Anthropic, OpenAI, MCP Registry, Google, Meta, Grok, Cursor and others): `docs/SUBMISSIONS.md`.
Bundles: `plugin/` (Claude plugin), `chatgpt/` (ChatGPT app package), `.cursor-plugin/` + `mcp.json` (Cursor plugin).

## About KeepMD

This server comes from [KeepMD](https://keepmd.org/), a family medical records app for tracking medical records,
labs and health documents for everyone you look after. The server is a separate reference service: it stores
nothing and never connects to anyone's records.

- [Secure medical records app](https://keepmd.org/secure-medical-records-app/)
- [How to organize family health records](https://keepmd.org/blog/organize-family-health-records/)
- [KeepMD on the App Store](https://apps.apple.com/us/app/keepmd-family-medical-records/id6759260249)
- [KeepMD on Google Play](https://play.google.com/store/apps/details?id=org.keepmd.app)

## License

MIT for code and KeepMD-authored content. Government data sources are public domain; see `NOTICE.md`.