# medical-codes-mcp-server [Health: Active]

**Category:** 🧬 Biology & Bioinformatics  
**Repository:** https://github.com/cyanheads/medical-codes-mcp-server  
**GitHub Stars:** 2  
**npm Downloads (last month):** 1495  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/medical-codes-mcp-server

## Description
Offline US medical code lookup and crosswalk — ICD-10-CM, ICD-10-PCS, HCPCS Level II. Keyless.

## Tools
Capabilities this server exposes over MCP:

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "medical-codes-mcp-server": {
    "command": "npx",
    "args": ["-y","@cyanheads/medical-codes-mcp-server"]
  }
}
```

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/medical-codes-mcp-server/readme_