io.github.Goingparabolic/painprep-mcp-server

Interventional pain medicine MCP: Medicare checklists, CPT/ICD-10, ASRA, prior-auth & appeals
Open source Open in the app JSON README (API)
About

Interventional pain medicine MCP: Medicare checklists, CPT/ICD-10, ASRA, prior-auth & appeals
Details

Kind: MCP servers
Topic: No topic detected
Publisher: goingparabolic
Origin: official
Category: ferramentas
Transport: local
Version: 0.1.2
Forks: 1
Last push: 2026-06-05T02:38:27Z
Repository state: sumiu
Language: TypeScript
License: MIT
Added: 2026-08-29 03:01:56
Updated: 2026-08-29 03:01:56
Origin id: io.github.Goingparabolic/painprep-mcp-server
README

# painprep-mcp-server

> An [MCP](https://modelcontextprotocol.io) server for **interventional pain medicine** — Medicare documentation checklists, CPT/ICD-10 coding, ASRA anticoagulation guidance, prior-authorization letters, denial appeals, and research evidence for 85+ procedures.

Built from [PainPrep](https://www.painprep.com) by Keith Schmidt, MD (triple board-certified pain medicine). This server makes PainPrep's clinical reference data available to any MCP client — Claude Desktop, Claude Code, or your own agent.

> ⚠️ **Clinical decision-support, not medical advice.** All output must be reviewed by a licensed clinician. Coding, coverage, and anticoagulation guidance change frequently — always verify against current CMS/LCD policy and the latest ASRA guidelines.

---

## What it does

| Tool | Tier | Description |
|---|---|---|
| `get_procedure_list` | **Free** | Full catalog of procedures grouped by category, with ids and headline CPT codes. |
| `get_cpt_codes` | **Free** | Primary + add-on CPT codes, work RVUs, facility setting, and billing notes. |
| `get_medicare_checklist` | Premium | Full LCD/Medicare documentation checklist with rationale, suggested wording, denial triggers, and admin checks. |
| `get_icd10_codes` | Premium | Approved/supportive ICD-10 codes, codes to **avoid**, and coding tips. |
| `get_contraindications` | Premium | Bleeding-risk tier + per-medication ASRA hold/resume guidance + safety checks. |
| `get_prior_auth_letter` | Premium | Generates a payer-ready prior-authorization / medical-necessity letter from patient details + procedure data. |
| `get_denial_reasons` | Premium | Common denial reasons with frequency, the fix for each, and an appeal letter snippet. |
| `get_research_evidence` | Premium | Evidence grade, summary, and key studies with citations. |
| `check_documentation_completeness` | Premium | Audits a note against the required checklist and scores completeness, highlighting commonly-missed gaps. |

Every tool accepts a procedure as a **name, id, or CPT code** (e.g. `"Lumbar/Sacral Interlaminar ESI"`, `"lesi"`, or `"62323"`). Unrecognized queries return "did you mean" suggestions.

---

## Quick start (no install)

The fastest way to run the server — `npx` clones, builds, and launches it in one step:

```bash
npx -y github:Goingparabolic/painprep-mcp-server
```

Or wire it straight into an MCP client (see [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)):

```json
{
  "mcpServers": {
    "painprep": {
      "command": "npx",
      "args": ["-y", "github:Goingparabolic/painprep-mcp-server"],
      "env": { "PAINPREP_LICENSE_KEY": "PP-XXXX-XXXX-XXXX" }
    }
  }
}
```

---

## Install & build (from source)

```bash
git clone https://github.com/Goingparabolic/painprep-mcp-server.git
cd painprep-mcp-server
npm install

# Extract the clinical data from the PainPrep source (one-time; see "Data" below)
npm run extract           # reads the PainPrep HTML → src/data/*.json

npm run build             # compile TypeScript → dist/ and copy data
npm run smoke             # end-to-end test (optional)
```

> The repository ships with the extracted JSON in `src/data/`, so `npm run extract` is only needed to regenerate it from an updated PainPrep source.

---

## Use with Claude Desktop

Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "painprep": {
      "command": "node",
      "args": ["/absolute/path/to/painprep-mcp-server/dist/index.js"],
      "env": { "PAINPREP_LICENSE_KEY": "PP-XXXX-XXXX-XXXX" }
    }
  }
}
```

Restart Claude Desktop. You'll then be able to ask things like:

- *"List the SI joint procedures."*
- *"What are the CPT codes and RVUs for lumbar RFA?"*
- *"Draft a prior-auth letter for a lumbar ESI for a patient with 5 months of L5 radiculopathy who failed 8 weeks of PT."*
- *"My note for an LESI documents MRI findings and pain score — what's missing for Medicare?"*

See [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) for an `npx` variant.

## Use with Claude Code

```bash
claude mcp add painprep -- node /absolute/path/to/painprep-mcp-server/dist/index.js
```

## Inspect locally

```bash
npm run inspect          # opens the MCP Inspector against the stdio server
```

---

## Remote hosting (HTTP / SSE)

The same tools are served over **Streamable HTTP** for remote deployment (MCPize, a VPS, or serverless):

```bash
npm run build
PORT=3000 node dist/http.js
# → POST http://localhost:3000/mcp     (GET /health for a liveness check)
```

The HTTP transport is **stateless and multi-tenant**: the per-customer license key is read from a request header, so a single deployment can serve many customers.

```
X-PainPrep-License: PP-XXXX-XXXX-XXXX     (preferred)
Authorization: Bearer PP-XXXX-XXXX-XXXX   (also accepted)
```

---

## Pricing & availability

| Tier | Price | Tools included |
|---|---|---|
| **Free** | $0 | `get_procedure_list`, `get_cpt_codes` |
| **Premium** | **$29/month** | All 9 tools — Medicare checklists, ICD-10 guidance, ASRA anticoagulation checks, prior-auth letters, denial appeals, research evidence, documentation auditing |

### Get Premium

Purchase a Premium license key via Stripe:

> **[Subscribe to PainPrep Premium ($29/mo)](https://buy.stripe.com/test/plink_1TckcpAOGBky7q8cI4yV4A2w)**

After subscribing you'll receive a license key in the format `PP-XXXX-XXXX-XXXX`. Set it in your MCP client configuration (see setup instructions above).

### Where to find PainPrep

PainPrep is available on multiple MCP marketplaces:

- **[MCPize Marketplace](https://mcpize.com/mcp/painprep)** — deploy-and-subscribe hosting with 80% revenue share
- **[Apify Store](https://apify.com/painprep/painprep-mcp)** — pay-per-event pricing, distributed across Make, n8n, and partner platforms
- **Self-hosted** — clone this repo and run it yourself (see Remote hosting above)

---

## Monetization & licensing

The server has a built-in **free / premium** split designed to be wired to a billing provider (Stripe, MCPize) with minimal change.

- **Free tier:** `get_procedure_list`, `get_cpt_codes`.
- **Premium tier:** everything else.

Premium tools are still *discoverable* (they appear in `tools/list` so clients can advertise the upgrade), but calling one without a valid entitlement returns an upgrade prompt instead of data.

### Entitlement resolution

Configured via environment variables (stdio) or request headers (HTTP):

| Variable | Purpose |
|---|---|
| `PAINPREP_LICENSE_KEY` | The customer's license key. |
| `PAINPREP_TIER` | Force `premium` or `free` (self-hosted / enterprise override). |
| `PAINPREP_VALID_KEYS` | Comma-separated allowlist of keys treated as valid premium (manual provisioning / testing). |
| `PAINPREP_LICENSE_VERIFY_URL` | Optional HTTP endpoint for **remote** key verification. When set, keys are validated against this service instead of locally. |

A locally-issued key matches the format `PP-XXXX-XXXX-XXXX`. For production, point `PAINPREP_LICENSE_VERIFY_URL` at your billing webhook; it should accept `{ "key": "..." }` and return `{ "valid": true, "tier": "premium", "expiresAt": "..." }`.

The verification layer lives entirely in [`src/licensing.ts`](src/licensing.ts) behind a `LicenseProvider` interface — swap the implementation without touching any tool.

---

## Project structure

```
painprep-mcp-server/
├── src/
│   ├── index.ts          # stdio entry point (Claude Desktop / Code)
│   ├── http.ts           # Streamable HTTP entry point (remote hosting)
│   ├── server.ts         # builds the MCP server + tier gating
│   ├── licensing.ts      # free/premium entitlement (pluggable)
│   ├── data.ts           # data loading + procedure resolver
│   ├── types.ts          # clinical data types
│   ├── tools/            # one file per MCP tool
│   └── data/             # extracted clinical data (JSON)
├── scripts/
│   ├── extract-data.mjs  # parse PainPrep HTML → src/data/*.json
│   ├── copy-assets.mjs   # copy JSON into dist/ at build
│   └── smoke-test.mjs    # end-to-end MCP client/server test
├── examples/
│   └── claude_desktop_config.json
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md
```

## Data

Clinical data is extracted from the PainPrep application source. The extractor
(`scripts/extract-data.mjs`) locates the embedded data objects (`CATEGORIES`,
`CHECKLISTS`, `ANTICOAG`, `MED_NECESSITY`, `ICD10_REF`, `DENIAL_TEMPLATES`,
`CPT_DETAILS`, `RESEARCH_EVIDENCE`), evaluates each literal in a sandbox, and
writes clean JSON to `src/data/`. To regenerate from an updated source:

```bash
npm run extract -- "/path/to/painprep-mvp.html"
```

---

## License

[MIT](LICENSE) © 2026 Keith Schmidt, MD

The clinical reference content is provided for educational and decision-support
purposes only and does not constitute medical advice.
io.github.Goingparabolic/painprep-mcp-server

About

Details

README

More
