@cyanheads/medical-codes-mcp-server
Decode, search, validate, and crosswalk US medical codes — ICD-10-CM, ICD-10-PCS, HCPCS Level II, RxNorm — over a bundled offline index via MCP. STDIO or Streamable HTTP.
6 Tools
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/medical-codes-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/medical-codes-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
[](https://github.com/cyanheads/medical-codes-mcp-server/releases/latest/download/medical-codes-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=medical-codes-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbWVkaWNhbC1jb2Rlcy1tY3Atc2VydmVyIl19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22medical-codes-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fmedical-codes-mcp-server%22%5D%7D)
**Public Hosted Server:** [https://medical-codes.caseyjhand.com/mcp](https://medical-codes.caseyjhand.com/mcp)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
---
> [!NOTE]
> **Informational, not clinical or coding advice.** This server returns official code descriptions and billable/validity flags from public-domain federal releases to help you decode and look up codes. It is **not** medical advice, and a `valid_billable` result is **not** a coding or reimbursement decision. Always verify codes against the official source releases (CMS, CDC/NCHS, NLM) and your payer's rules before submitting a claim. The bundled data is only as current as the release baked into the build — call `medcode_list_systems` to see exactly which releases are active.
## Overview
US medical codes — ICD-10-CM, ICD-10-PCS, HCPCS Level II, and RxNorm with RxClass drug classes — searchable offline from official federal releases. Decode, search, check billability, and crosswalk codes, drugs, NDCs, and drug classes.
### Tools
| Tool | Description |
|:---|:---|
| `medcode_get_code` | Decode 1–50 codes to their official descriptions. Auto-detects the system per code; partial-success `found` / `notFound`, with codes past a 24,000-byte reply returned in `deferred` for the next call. |
| `medcode_search_codes` | Full-text search over official descriptions — go from a clinical description to the code. |
| `medcode_check_code` | Validate a code's existence, currency, and billability, with a `whyNot` for non-billable/terminated cases. |
| `medcode_map_codes` | Crosswalk a code within its hierarchy (`parents`/`children`), a drug across RxNorm (name ↔ RXCUI, NDC ↔ RXCUI, RXCUI → ingredients/brands), or a drug to its RxClass classes and a class to its member drugs. |
| `medcode_browse_hierarchy` | Walk a system's hierarchy for discovery without a search term. |
| `medcode_list_systems` | List bundled systems with release identifiers, effective dates, and code counts, and the RxClass layer with each source's version (provenance). |
## How it works
Only freely-redistributable, public-domain US federal code sets are bundled, baked into a single SQLite + FTS5 database at package-build time and opened read-only at startup.
### Bundled code systems
| System | Source | Covers |
|:---|:---|:---|
| **ICD-10-CM** | [CDC/NCHS](https://www.cdc.gov/nchs/icd/icd-10-cm/index.html) — US federal, public domain | Diagnoses (billable leaf codes + non-billable category headers) |
| **ICD-10-PCS** | [CMS](https://www.cms.gov/medicare/coding-billing/icd-10-codes) — US federal, public domain | Inpatient procedures (axis-based 7-character codes) |
| **HCPCS Level II** | [CMS](https://www.cms.gov/medicare/coding-billing/healthcare-common-procedure-system) — US federal, public domain | Supplies, drugs, and non-physician services |
| **RxNorm** | [NLM RxNav](https://rxnav.nlm.nih.gov/) — public domain | Drugs: name ↔ RXCUI, NDC ↔ RXCUI crosswalk, ingredients, and brands |
| **RxClass drug classes** | [NLM RxClass](https://lhncbc.nlm.nih.gov/RxNav/applications/RxClassIntro.html) — US government sources only | Classes of the RxNorm drugs: pharmacologic class, mechanism of action, physiologic effect, pharmacokinetics, therapeutic category, chemical structure, diseases treated/prevented and contraindications, VA class, DEA schedule, CVX vaccine code |
**RxNorm** bundles the current normalized drug vocabulary — ingredients, brand names, clinical & branded drugs, and packs, with their NDC and ingredient/brand crosswalks — sourced at build time from the keyless [RxNav REST API](https://rxnav.nlm.nih.gov/), which serves the public-domain normalized layer only. The full UMLS-licensed RxNorm release is intentionally excluded, so the package stays freely redistributable.
**RxClass** is a class layer over those drugs, not a code system: 20,723 classes and 87,269 drug–class edges, fetched at build time from the keyless [RxClass API](https://rxnav.nlm.nih.gov/REST/rxclass/). Six sources are bundled, all US government works: `MEDRT` (VA MED-RT — mechanism, physiologic effect, pharmacokinetics, chemical structure, and disease relations), `FDASPL` (FDA established pharmacologic classes and related classes from structured product labels), `FMTSME` (therapeutic categories), `VA` (VA National Formulary classes), `RXNORM` (DEA controlled-substance schedules), and `CDC` (CVX vaccine codes). Four are excluded: `ATC` and `ATCPROD`, whose WHO terms bar copying and distribution for commercial purposes; `SNOMEDCT`, which is under the SNOMED CT Affiliate license; and `DAILYMED`, which repeats FDASPL's edges almost exactly (8,696 of its 8,710) and publishes no version.
> This product uses publicly available data courtesy of the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services; NLM is not responsible for the product and does not endorse or recommend this or any other product.
CPT (AMA copyright) and SNOMED CT / LOINC (UMLS-license-gated) are intentionally absent — not freely redistributable, so they cannot ship in an offline package.
**US scope.** ICD-10-CM and ICD-10-PCS are the US clinical modifications, not the WHO ICD-10/ICD-11 base or another country's national modification.
## Capability reference
### `medcode_get_code` tool
- Accepts 1–50 codes; mixed systems are fine — each code's system is detected independently from its shape
- Decodes a National Drug Code (NDC) directly to its RxNorm product — hyphenated FDA segment configurations (4-4-2, 5-3-2, 5-4-1, or the 11-digit 5-4-2) or bare 10/11 digits — offline via the bundled NDC↔RxNorm map, tagged `source: "NDC"`
- Partial success: resolved codes in `found`, unresolved in `notFound` with a per-code reason — a bare integer that resolves nowhere is named as a possible CPT / HCPCS Level I code, which is out of scope, except a bare 10/11-digit one, which is named as an NDC no bundled drug maps to; a dotted all-digit value in ICD-9-CM form (`250.00`) is named as ICD-9-CM, which is not bundled; and an ICD-10-PCS section value (`0`) looked up under `system: "ICD10PCS"` is named as a section, not a code
- A code written in ICD-10-CM dotted form (`A01.00`) resolves to ICD-10-CM; an explicit `system` overrides auto-detection when a value is genuinely ambiguous (an ambiguous code lists its `candidateSystems`) and skips the NDC decode; `includeHierarchy` attaches each code's parent and immediate children
- Each reply holds `structuredContent` and the `content[]` text to 24,000 bytes apiece. Codes are decoded in request order, and once one has resolved, a code that would carry the reply past the budget comes back unprocessed in `deferred`, as sent, with every code after it. Re-call with `codes` set to `deferred` and the same `system` and `includeHierarchy` until no `deferred` comes back; together the replies hold the same `found` and `notFound`, in the same order, that one unbounded reply would. Three kinds of code are never deferred and can carry a reply past the budget: the first code that resolves, which always comes back whole (under a raised `MEDCODE_MAX_RESULTS`, one code with hundreds of children passes the budget on its own); the codes before it; and the unresolved codes after the last one that resolves, so a re-call always holds a code that resolves and never fails with `no_codes_found` or `ambiguous_system`
- `alsoInSystems` names other bundled systems holding the same code string — it is a different code in each
- RxNorm rows carry `billable: null` (RxNorm has no billing concept) and `shortDescription: null` (RxNorm publishes a single name); `chapter` holds the RxNorm term type (`IN`, `SCD`, `SBD`, …)
- Errors: `ambiguous_system` when every requested code is present in more than one bundled system and no `system` is given, with the union of those systems in `candidateSystems`; `no_codes_found` when none of the requested codes resolve otherwise — in any bundled system, or under an explicit `system` in that system — naming any other bundled system that holds a code, each code present in more than one system, and the section values, bare integers, ICD-9-CM forms, and NDCs among the misses
---
### `medcode_search_codes` tool
- Every search term must appear — matched first as a token prefix, then as a substring, so inflected and compound forms are also found; an RxNorm concept matches on its drug name alone, never its term type
- Filter by `system`, `billableOnly` (exclude headers/categories, terminated HCPCS codes, and every RxNorm concept — RxNorm has no billing concept), and `chapter` (for RxNorm, the term type)
- Ranked by full-text relevance; results echo the resolved `system` per row
- Paginates via `cursor`/`limit` (default `MEDCODE_MAX_RESULTS`, ceiling 200); discloses `truncated`/`nextCursor`, and returns a notice with the parsed query when nothing matches
---
### `medcode_check_code` tool
- Discriminated `status`: `valid_billable`, `valid_not_billable`, `valid_header`, `valid`, or `terminated` — `valid_header` covers an ICD-10-CM category, a HCPCS range bucket, and an ICD-10-PCS table row; `valid` is a current RxNorm concept, returned with `billable: null` because RxNorm has no billing concept
- `whyNot` explains non-billable/terminated cases — a non-billable or terminated code is a successful result, not an error
- A HCPCS code is `terminated` once its termination date (the last date CMS allows it on a claim) has passed, read against the UTC date of the call; until then it checks as billable, with that date in `whyNot`
- A code written in ICD-10-CM dotted form (`A01.00`) resolves to ICD-10-CM; `alsoInSystems` names other bundled systems holding the same code string, since the verdict applies only to the resolved system
- Errors: `unknown_code` (absent from the named system, or with no `system` from every bundled system, naming every system the code's shape fits (for a dotted ICD-10-CM form, ICD-10-CM alone) — under an explicit `system`, a code another bundled system holds is named as that system's code, and under `ICD10PCS` a section value (`0`) as a section that `medcode_browse_hierarchy` lists; a dotted all-digit value in ICD-9-CM form (`250.00`, `724.2`) is never read as an RXCUI and is named as ICD-9-CM, which is not bundled; an NDC lands here too, including a well-formed bare 10/11-digit one no bundled drug maps to, with a recovery pointing at `medcode_get_code` and `medcode_map_codes` `ndc_to_rxcui`) and `ambiguous_system` (present in multiple systems, no `system` given)
---
### `medcode_map_codes` tool
- Hierarchy directions `parents`/`children` walk one level per call (depth-1). A code's parent is the nearest ancestor the release holds as a code: an ICD-10-CM code padded with the placeholder X steps past a padding level that is not a code (`S82.66XA` → `S82.66`). An ICD-10-PCS three-character table row's children are the complete codes that begin with it, and a complete code's parent is its table row (`0DTJ4ZZ` → `0DT`). RxNorm concepts have no code hierarchy
- Drug directions (RxNorm): `name_to_rxcui` (matches the drug name, never the term type), `ndc_to_rxcui`/`rxcui_to_ndc` (NDC accepted hyphenated in an FDA segment configuration — 4-4-2, 5-3-2, 5-4-1, or the 11-digit 5-4-2 — or as bare 10/11 digits), `rxcui_to_ingredients`/`rxcui_to_brands`. Each `name_to_rxcui`, `ndc_to_rxcui`, `rxcui_to_ingredients`, and `rxcui_to_brands` hit carries the target's `conceptType`: `IN`/`PIN`/`MIN`/`BN` for ingredients and brands, `SCD`/`SBD`/`GPCK`/`BPCK` for drug products (every `ndc_to_rxcui` hit is one)
- Drug-class directions (RxClass): `rxcui_to_classes` returns an RXCUI's classes, and `class_to_rxcuis` a class ID's direct member RXCUIs, each with its RxNorm name and `conceptType`. Each hit carries `classType`, `source` (the RxClass source asserting it), and `relation` (`has_epc`, `may_treat`, …) — one hit per class × source × relation. A relation starting `ci_` (`ci_with`, `ci_moa`, `ci_pe`, `ci_chemclass`) is a contraindication, not an indication
- RxClass attaches most classes to ingredients, so a drug product also returns its ingredients' classes, naming the ingredient in `via` (an `IN` over its `PIN`); inheritance runs upward only. DEA schedules are recorded only on drug products, and VA classes almost only there: map a product for those — an ingredient's empty `SCHEDULE` or `VA` result says so rather than reading as unscheduled or unclassified. Membership is direct: a class whose drugs all attach to its subclasses (`N0000193873` "Diuretic") returns no members, and the class hierarchy is not walked
- Class IDs match case-insensitively, and a one-digit CVX vaccine code reads as its zero-padded ID (`3` is CVX `03`)
- `classType` (`EPC`, `MOA`, `PE`, `PK`, `TC`, `CHEM`, `DISEASE`, `VA`, `SCHEDULE`, `CVX`) narrows the two class directions and is rejected on every other
- `children`, `name_to_rxcui`, `rxcui_to_ndc`, `rxcui_to_classes`, and `class_to_rxcuis` paginate via `cursor`/`limit` — one RXCUI can carry thousands of package NDCs and one class thousands of members; `limit` and `cursor` are rejected on every other direction, and `system` steers only `parents`/`children` (the drug and class directions accept only `RXNORM`)
- Every hit carries `source` provenance so a chained call uses the right identifier; a resolvable source with no edge in the requested direction is a successful empty result with a notice, not an error — a brand name has no classes, for instance
- Errors:
- `no_mapping`: the source doesn't resolve. The message names what was sent instead when it can tell: a code-system name (recovered to the input the direction takes), an NDC or class ID where an RXCUI belongs, a bare integer that may be an out-of-scope CPT / HCPCS Level I code, a dotted all-digit value in ICD-9-CM form (not bundled), an ICD-10-PCS section value under `system: "ICD10PCS"`, or a code that another bundled system holds. An `ndc_to_rxcui` miss says whether the NDC is malformed or simply maps to no bundled drug
- `field_not_applicable`: a `system`, `classType`, `limit`, or `cursor` the direction does not use
- `direction_unavailable`: RxNorm, or for the class directions the RxClass layer, is not bundled in this build
- `ambiguous_system`
---
### `medcode_browse_hierarchy` tool
- With no `node`: top-level entries (ICD-10-CM categories, HCPCS range buckets, ICD-10-PCS first-axis values); with a `node`: its immediate children
- ICD-10-CM/HCPCS use a prefix hierarchy; ICD-10-PCS is axis-based and only the top-level Section axis is browsable — positions 2–7 are context-dependent and not enumerable from a flat partial code, so `medcode_map_codes` `children` lists the complete codes in a table row
- Paginates via `cursor`/`limit` (default `MEDCODE_MAX_RESULTS`, ceiling 200)
- Errors: `unknown_node` when the node doesn't exist (or, for ICD-10-PCS, uses an out-of-alphabet character or begins no bundled code)
---
### `medcode_list_systems` tool
- No input; returns one entry per bundled system with `releaseId`, `effectiveStart`/`effectiveEnd`, `codeCount`, `sourceUrl`, and `builtAt`
- `builtAt` dates the system's data: for ICD-10-CM, ICD-10-PCS, and HCPCS, the time the index was built from the named release; for RxNorm, which publishes no release label, the date the RxNav snapshot was fetched, so a rebuild from the same snapshot reports the same date
- `classLayer` reports the RxClass layer apart from the code systems: its class and edge counts, and per source the RxClass version (null where RxClass publishes none — CDC), the classes and edges it contributes, and the date the RxClass snapshot was fetched; null on a build without the layer
- Confirms exactly which ICD-10-CM/PCS fiscal year, HCPCS release, RxNorm snapshot, and RxClass sources are baked into the running build
## Features
Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
ICD-10 / HCPCS / RxNorm-specific:
- Bundled SQLite + FTS5 index — offline, keyless, deterministic; no runtime network I/O, no rate limit
- Code-shape auto-detection routes a code to its system automatically, and a code in ICD-10-CM dotted form resolves to ICD-10-CM, while a dot between two digits keeps a value from being read as an RXCUI; an explicit `system` disambiguates collisions
- Real billable/validity signal from the source releases — the order-file billable flag and, for HCPCS, the termination date read against the date of the call drive `medcode_check_code`, not a heuristic; RxNorm, which has no billing concept, reports `billable: null` rather than a verdict
Agent-friendly output:
- Provenance on every response — the resolved `system` is echoed for chaining, `alsoInSystems` flags a code string that means something different in another bundled system, and `medcode_list_systems` reports exactly which release is baked into the build
- Graceful partial failure — `medcode_get_code` returns per-code `found`/`notFound` rows instead of failing the batch
- Discriminated output contracts — `medcode_check_code`'s typed `status` and `medcode_map_codes`' `source` let callers branch on data, not string parsing
## Getting started
The code database ships with the server — there is no API key to obtain and nothing to download at runtime.
Connect to the hosted instance, no install:
```sh
claude mcp add --transport http medical-codes-mcp-server https://medical-codes.caseyjhand.com/mcp
```
Or run it locally:
```sh
claude mcp add medical-codes-mcp-server -- npx -y @cyanheads/medical-codes-mcp-server
```
For other clients, add this to the MCP config file:
```json
{
"mcpServers": {
"medical-codes-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/medical-codes-mcp-server"]
}
}
}
```
For Docker or a source build, see [Running the server](#running-the-server).
## Configuration
The server is offline and keyless — there are no required variables. Two server-specific knobs and the standard framework vars apply:
| Variable | Description | Default |
|:---|:---|:---|
| `MEDCODE_DB_PATH` | Absolute path override for the bundled SQLite index. Set only to point at a custom-built or externally-mounted database. | packaged `data/medical-codes.db` |
| `MEDCODE_MAX_RESULTS` | Default page size when a call sends no `limit` — `medcode_search_codes`, `medcode_browse_hierarchy`, and the paginated `medcode_map_codes` directions — and the number of children `medcode_get_code` attaches with `includeHierarchy`. | `50` (ceiling `200`) |
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
| `MCP_HTTP_ENDPOINT_PATH` | Endpoint path where the MCP server is mounted. | `/mcp` |
| `MCP_SESSION_MODE` | HTTP session handling: `stateless`, `stateful`, or `auto` (which resolves to `stateful`). `src/index.ts` declares `stateless` — no tool asks the caller for input mid-call — and this variable overrides that declaration. | `stateless` |
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
| `LOG_TOOL_FAILURE_PAYLOADS` | Log each failed tool call's arguments and result (key-name redaction only), capped by `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`. | `false` |
| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP base URL; traces export to `/v1/traces` and metrics to `/v1/metrics`. | — |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Opt-in OTLP log export; the base endpoint never enables it. | — |
See [`.env.example`](./.env.example) for the full list of optional overrides.
## Running the server
### Local development
Requires [Bun v1.4](https://bun.sh/) or higher (or Node.js v24+ — the server falls back to the `better-sqlite3` optional dependency when not run under Bun).
- **Clone and install:**
```sh
git clone https://github.com/cyanheads/medical-codes-mcp-server.git
cd medical-codes-mcp-server && bun install
cp .env.example .env # optional — every runtime var has a default
```
- **Build and run:**
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:stdio
# or
bun run start:http
```
- **Run checks and tests:**
```sh
bun run devcheck # Lint, format, typecheck, security
bun run test # Vitest test suite
bun run lint:mcp # Validate MCP definitions against spec
```
### Building the bundled index
The bundled `data/medical-codes.db` ships in the npm package and Docker image but, at over 100 MB, is not committed to git; a clone gets a prebuilt copy from the npm package or the `.mcpb` attached to each [GitHub Release](https://github.com/cyanheads/medical-codes-mcp-server/releases). Rebuilding is only needed to refresh to a new federal release, and runs offline from source files you download first. The steps are in [docs/building-the-index.md](./docs/building-the-index.md).
### Docker
```sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/medical-codes-mcp-server:latest
```
The image defaults to HTTP transport, stateless session mode, and logs to `/var/log/medical-codes-mcp-server`, and carries the bundled `data/medical-codes.db`, so it is fully self-contained. To run it over stdio from an MCP client, use `"command": "docker"` with `"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/medical-codes-mcp-server:latest"]`. To build locally, `docker build -t medical-codes-mcp-server .`; OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
## Project structure
| Directory | Purpose |
|:---|:---|
| `src/index.ts` | `createApp()` entry point — registers the six tools and opens the bundled index in `setup()`. |
| `src/config` | Server-specific environment variable parsing and validation with Zod. |
| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |
| `src/services/code-index` | The code-index service — read-only SQLite handle, code-shape detection, FTS5 query translation. |
| `scripts/build-index.ts` | Build-time ingest pipeline that bakes the federal source files into `data/medical-codes.db`. |
| `data/medical-codes.db` | The bundled SQLite + FTS5 code index, opened read-only at runtime. |
| `tests/` | Unit and integration tests mirroring `src/`. |
## Development guide
See [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no `try/catch` in tool logic
- Use `ctx.log` for request-scoped logging; the code index is a read-only global, not tenant state
- Register new tools via the `createApp()` array in `src/index.ts`
- The bundled DB is the source of truth — surface real billable/validity flags from the source releases; never fabricate a code or a billability decision
## Contributing
Issues are welcome. Run checks and tests before submitting:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](./LICENSE) for details.