Medical Codes MCP Server

What medical-codes-mcp-server does

medical-codes-mcp-server gives MCP-compatible agents access to freely redistributable US code and drug data without making live lookup requests at runtime. Its bundled systems include ICD-10-CM for diagnoses, ICD-10-PCS for inpatient procedures, HCPCS Level II for supplies, drugs, and non-physician services, and RxNorm for normalized medication concepts and NDC relationships.

The package also includes an RxClass layer over RxNorm drugs. Its government-sourced class relationships cover areas such as pharmacologic classes, mechanisms of action, therapeutic categories, DEA schedules, vaccine codes, and diseases treated or prevented. RxClass is presented as a drug-class layer rather than another medical code system.

CPT, SNOMED CT, LOINC, WHO ICD-10, and ICD-11 are outside the bundled scope. ICD-10-CM and ICD-10-PCS specifically represent the US clinical modifications.

How it works

Data is assembled during package build time into a read-only SQLite database with FTS5 indexes. The server opens that database at startup, so normal lookups work offline and require no API key. RxNorm and RxClass source data is fetched during the build process from public NLM services, while the medical code sets come from public-domain federal releases.

The tools can auto-detect a code system from a value's form, while an explicit system can resolve genuinely ambiguous values. NDCs may be supplied in supported hyphenated segment layouts or as 10- or 11-digit values. Results preserve request order, and batch decoding accepts from one to 50 codes.

Setup and configuration

The server can be installed through the package's npx invocation, including the one-click configurations offered for Claude Desktop, Cursor, and VS Code. It supports both STDIO and Streamable HTTP transports. A hosted MCP endpoint is also available at https://medical-codes.caseyjhand.com/mcp.

The package is keyless. Its bundled data is fixed at build time; use medcode_list_systems to inspect the release identifiers, effective dates, counts, and source versions included in a particular build.

Tools and capabilities

• medcode_get_code decodes up to 50 mixed-system codes, including direct NDC-to-RxNorm resolution. It returns successful and unresolved items separately, with per-code reasons for failures. Parent and immediate-child information can be included.
• medcode_search_codes performs full-text searches over official descriptions, supporting discovery from a clinical phrase.
• medcode_check_code reports whether a code exists, is current, and is billable. Non-billable or terminated results can include an explanation.
• medcode_map_codes follows code parents and children, maps drug names, RXCUIs, and NDCs, and relates drugs to RxClass classes or classes to member drugs.
• medcode_browse_hierarchy explores a code system without requiring a search term.
• medcode_list_systems reports bundled systems, release metadata, effective dates, code counts, and RxClass provenance.

Large decode responses are split around a 24,000-byte limit. Items that would exceed the response budget are returned as deferred work for a subsequent call.

Limitations and notes

Results are informational lookup data, not medical advice, coding advice, or reimbursement decisions. A valid and billable result does not determine whether a code is appropriate for a claim. Verify codes against the relevant CMS, CDC/NCHS, or NLM release and the payer's rules before submission.

The available data depends on the release baked into the installed package. The RxNorm bundle uses the public-domain normalized layer rather than the UMLS-licensed release. RxClass includes selected US government sources and excludes sources whose licensing terms prevent redistribution.

A code that belongs to an excluded system, such as CPT or SNOMED CT, cannot be resolved from the offline index. The server also distinguishes unsupported formats and hierarchy section values from valid code matches.