Medical Codes MCP Server

@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

Public Hosted Server: https://medical-codes.caseyjhand.com/mcp

[!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 sy