@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
[!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
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
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, 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. 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 otherchildren, 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 drugfield_not_applicable: a system, classType, limit, or cursor the direction does not usedirection_unavailable: RxNorm, or for the class directions the RxClass layer, is not bundled in this buildambiguous_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 dateclassLayer 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: 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:
Or run it locally:
For other clients, add this to the MCP config file:
For Docker or a source build, see 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:
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4 or higher (or Node.js v24+ — the server falls back to the better-sqlite3 optional dependency when not run under Bun).
-
Clone and install:
-
Build and run:
-
Run checks and tests:
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. 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.
Docker
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
Development guide
See CLAUDE.md/AGENTS.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:
License
Apache-2.0 — see LICENSE for details.
