io.github.Goingparabolic/painprep-mcp-server

Official

by Goingparabolic · TypeScript

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

Interventional pain medicine server providing Medicare checklists, CPT codes, and prior-auth guidance.

Topics

anthropicanticoagulationasraclaudeclinical-decision-supportcpt-codeshealthcareicd-10mcpmedical-codingmedicaremodel-context-protocolpain-medicineprior-authorizationinterventional-pain

README.md9 KBView on GitHub

painprep-mcp-server

An MCP 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 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):

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 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.

code

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)

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 — deploy-and-subscribe hosting with 80% revenue share
Apify Store — 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 behind a LicenseProvider interface — swap the implementation without touching any tool.

Project structure

code

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

The clinical reference content is provided for educational and decision-support purposes only and does not constitute medical advice.

Install

Configuration

Environment variables

PAINPREP_LICENSE_KEYsecret

PainPrep PREMIUM license key (PP-XXXX-XXXX-XXXX). Optional — the free tier works without it.

claude_desktop_config.json

{
  "mcpServers": {
    "painprep-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "painprep-mcp-server@0.1.2"
      ],
      "env": {
        "PAINPREP_LICENSE_KEY": "<YOUR_PAINPREP_LICENSE_KEY>"
      }
    }
  }
}