io.github.cyanheads/medical-codes-mcp-server

Official6 tools

by cyanheads · TypeScript

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

Offline lookup and crosswalk of US medical codes including ICD-10, HCPCS, and RxNorm.

Topics

aibunhcpcshealthcareicd-10llmmcpmcp-servermedical-codesmedical-codingmodel-context-protocoltypescriptai-agentscyanheadsndcrxnorm

Captured live from the server via tools/list.

medcode_get_code

Decode one or more US medical codes to their official descriptions across ICD-10-CM (diagnoses), ICD-10-PCS (inpatient procedures), HCPCS Level II (supplies/drugs/services), and RxNorm (drugs, by RXCUI). Also decodes a National Drug Code (NDC) — hyphenated or 10/11-digit — directly to its RxNorm product offline, tagged `source: "NDC"`. Auto-detects the system from each code's shape; pass an explicit `system` only when a value is genuinely ambiguous. Accepts 1–50 codes and returns partial success: resolved codes in `found`, unresolved in `notFound` with a per-code reason, so one bad code never fails the batch. Set `includeHierarchy` to attach each code's parent and immediate children. The resolved `system` is echoed on every result for chaining into medcode_map_codes or a billability check.

Parameters (3)

codesarrayrequired
Codes to decode (1–50). Mixed systems are fine — each is detected independently. An NDC (hyphenated or 10/11-digit) decodes to its RxNorm product.
systemstring
Force every code to be looked up in this system. Omit to auto-detect per code.
includeHierarchyboolean
When true, attach each found code's parent and immediate children.

medcode_search_codes

Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index. Every search term must appear (prefix-matched), so "diabetic neuropathy" returns codes mentioning both. Filter by `system` (ICD10CM/ICD10PCS/HCPCS/RXNORM), `billableOnly` to exclude headers/categories, and `chapter`. Use when you have a clinical description and need the code — the reverse of medcode_get_code. Results echo the resolved system per row for chaining, and disclose truncation when the result hits the cap.

Parameters (5)

querystringrequired
Clinical description to match, e.g. "type 2 diabetes with neuropathy".
systemstring
Restrict results to one system. Omit to search all bundled systems.
billableOnlyboolean
When true, return only billable leaf codes (exclude headers/categories).
chapterstring
Restrict to a chapter/range bucket (the value from a code's `chapter` field).
limitinteger
Max codes to return. Defaults to the server's MEDCODE_MAX_RESULTS (50), ceiling 200.

medcode_check_code

Validate whether a US medical code exists, is current, and is billable in the active bundled release. Returns a discriminated status — valid_billable, valid_not_billable, valid_header, or terminated — with a `whyNot` explaining non-billable and terminated cases (e.g. "valid ICD-10-CM category but not billable — submit a more specific child code"). This is the detail a coder needs before submitting a claim. Auto-detects the system from the code's shape; pass an explicit `system` to disambiguate. A non-billable or terminated code is a successful result with a whyNot, not an error — only a code that exists in no bundled system raises unknown_code.

Parameters (2)

codestringrequired
The code to validate, with or without dots.
systemstring
Force the lookup into this system. Omit to auto-detect from the code's shape.

medcode_map_codes

Crosswalk a US medical code or drug across systems and within a hierarchy. Hierarchy directions: `parents` and `children` walk a code's prefix hierarchy one level per call — immediate parent/children only (depth-1); call iteratively for the full ancestor or descendant path (ICD-10-CM/HCPCS; ICD-10-PCS codes have no prefix parent). A resolvable code with no edge in the requested direction is a successful empty result with a notice, not an error. Drug directions (RxNorm): `name_to_rxcui` (drug name → RXCUI), `ndc_to_rxcui` and `rxcui_to_ndc` (NDC ↔ RXCUI; NDCs accepted hyphenated or 10/11-digit), `rxcui_to_ingredients` and `rxcui_to_brands` (RXCUI → ingredient/brand RXCUIs). Every result carries `source` provenance (which system or edge answered) so a chained call (e.g. into openfda with a resolved NDC) uses the right identifier.

Parameters (3)

fromstringrequired
The source value: a code (for parents/children), a drug name, an NDC, or an RXCUI.
directionstringrequired
What to map to. parents/children return the immediate parent or children only (depth-1) — call iteratively to walk a full path; the rxcui/ndc/name directions are RxNorm drug crosswalks.
systemstring
For parents/children, force the source code into this system. Omit to auto-detect.

medcode_browse_hierarchy

Walk a US medical code system's hierarchy for discovery without a search term. With no `node`, returns the top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values). With a `node`, returns its immediate children. ICD-10-CM and HCPCS use a prefix hierarchy (a shorter code is the parent of a longer one); ICD-10-PCS is axis-based — each of its 7 characters is an independent axis (section, body system, root operation, body part, approach, device, qualifier), but only the top-level Section axis is browsable (omit `node`): positions 2–7 are context-dependent on the preceding axis path and are not enumerable from a flat partial code. Lets an agent orient in an unfamiliar system or enumerate a category's specific codes.

Parameters (3)

systemstringrequired
The code system to browse.
nodestring
A node to expand. For ICD-10-CM/HCPCS, a code whose children to list. ICD-10-PCS supports only top-level Section browsing (omit `node`) — a partial PCS code does not expand to next-position axis values. Omit for the top level.
limitinteger
Max entries to return. Defaults to MEDCODE_MAX_RESULTS (50), ceiling 200.

medcode_list_systems

List the bundled US medical code systems with their release identifiers, effective dates, and code counts. Confirms which ICD-10-CM fiscal year, ICD-10-PCS fiscal year, HCPCS Level II release, and RxNorm Prescribable Content snapshot are active before acting on any decode, search, or crosswalk result. The corpus is offline and built at package-build time — this call reports exactly which release is baked into the running server. ICD-10-CM/PCS are the US clinical modifications, not the ICD-10/ICD-11 base.

No parameters.

README.md17 KBView on GitHub

<div align="center"> <h1>@cyanheads/medical-codes-mcp-server</h1> <p><b>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.</b> <div>6 Tools</div> </p> </div> <div align="center">

</div> <div align="center">

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

</div> <div align="center">

</div>

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.

How it works

The code data is bundled inside the package — a single SQLite + FTS5 database (data/medical-codes.db) built at package-build time from the canonical federal source files and shipped in the npm tarball and Docker image. The server opens it read-only at startup and answers every tool call from disk.

That means the server is offline, keyless, and deterministic: no runtime network calls, no API key, no rate limit, single-tenant. The same inputs against the same bundled build always return the same output.

Bundled code systems

Only freely-redistributable, public-domain US federal code sets are bundled:

System	Source	Covers
ICD-10-CM	CDC/NCHS — US federal, public domain	Diagnoses (billable leaf codes + non-billable category headers)
ICD-10-PCS	CMS — US federal, public domain	Inpatient procedures (axis-based 7-character codes)
HCPCS Level II	CMS — US federal, public domain	Supplies, drugs, and non-physician services
RxNorm	NLM RxNav — public domain	Drugs: name ↔ RXCUI, NDC ↔ RXCUI crosswalk, ingredients, and brands

RxNorm bundles the current RxNorm normalized drug vocabulary — ingredients, brand names, clinical & branded drugs, and packs, with their NDC and ingredient/brand crosswalks. It is sourced at build time from the keyless RxNav REST API, which serves the public-domain normalized layer — never the UMLS-licensed source vocabularies, so it stays freely redistributable in an offline package. (The full UMLS RxNorm release, which pulls in those licensed sources, is intentionally excluded.) This powers medcode_map_codes' drug directions and direct NDC → drug decode in medcode_get_code.

CPT (AMA copyright) and SNOMED CT / LOINC (UMLS-license-gated) are intentionally absent — they are 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.

Tools

Six tools organized goal-first — one per user action, with a system discriminator instead of a per-system tool for each of the bundled code sets. All are read-only.

Tool	Description
`medcode_get_code`	Decode 1–50 codes to their official descriptions. Auto-detects the system per code; partial-success `found` / `notFound`.
`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`) or a drug across RxNorm (name ↔ RXCUI, NDC ↔ RXCUI, RXCUI → ingredients/brands).
`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 (provenance).

`medcode_get_code`

Decode one or more codes seen in a claim, EHR field, or another health server's output. The 80% entry point.

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 (0777-3105-02) or 10/11-digit — offline via the bundled NDC↔RxNorm map, tagged source: "NDC"
Partial success: resolved codes in found, unresolved in notFound with a per-code reason, so one bad code never fails the batch
An explicit system overrides auto-detection when a value is genuinely ambiguous (an ambiguous code lists its candidateSystems)
includeHierarchy attaches each code's parent and immediate children
The resolved system is echoed on every result for chaining into medcode_map_codes or a billability check

`medcode_search_codes`

Find codes whose official descriptions match a described concept — the reverse of medcode_get_code.

Every search term must appear (prefix-matched), so "diabetic neuropathy" returns codes mentioning both
Filter by system, billableOnly (exclude headers/categories), and chapter
Ranked by full-text relevance; results echo the resolved system per row
Discloses truncation when the result hits the cap, and returns an explicit notice (with the parsed query) when nothing matched

`medcode_check_code`

Validate whether a code is safe to submit, before a claim goes out.

Discriminated status: valid_billable, valid_not_billable, valid_header, or terminated
A whyNot string explains the non-billable and terminated cases (e.g. "valid ICD-10-CM category but not billable — submit a more specific child code")
Validity vs. existence is split: a non-billable or terminated code is a successful result with a whyNot, not an error — only a code absent from every bundled system raises unknown_code

`medcode_map_codes`

Crosswalk a code across systems and within a hierarchy.

Hierarchy directions: parents and children walk a code's prefix hierarchy one level per call — immediate parent/children only (depth-1); call iteratively for the full path (ICD-10-CM / HCPCS; ICD-10-PCS codes have no prefix parent)
Drug directions (RxNorm): name_to_rxcui (drug name → RXCUI), ndc_to_rxcui / rxcui_to_ndc (NDC ↔ RXCUI; NDCs accepted hyphenated or 10/11-digit), rxcui_to_ingredients / rxcui_to_brands (RXCUI → ingredient/brand RXCUIs)
Every result carries source provenance (which system or edge answered) so a chained call uses the right identifier

`medcode_browse_hierarchy`

Orient in an unfamiliar system or enumerate a category's specific codes, without a search term.

With no node: top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values)
With a node: its immediate children
ICD-10-CM and HCPCS use a prefix hierarchy (a shorter code is the parent of a longer one); ICD-10-PCS is axis-based — only the top-level Section axis is browsable; positions 2–7 are context-dependent on the preceding axis path and aren't enumerable from a flat partial code

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling — handlers throw, framework catches, classifies, and formats
Typed per-tool error contracts — capable clients preview failure modes from tools/list
Structured logging with optional OpenTelemetry tracing
STDIO and Streamable HTTP transports

Domain-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; an explicit system disambiguates collisions
Real billable/validity signal from the source releases — the order-file billable flag drives medcode_check_code, not a heuristic

Agent-friendly output:

Provenance on every response — the resolved system is echoed for chaining, and medcode_list_systems reports exactly which release is baked into the running 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

This server ships with the code database bundled — there is no API key to obtain and nothing to download at runtime.

Public Hosted Instance

A public instance is available at https://medical-codes.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

json

{
  "mcpServers": {
    "medical-codes-mcp-server": {
      "type": "streamable-http",
      "url": "https://medical-codes.caseyjhand.com/mcp"
    }
  }
}

Self-hosted

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "medical-codes-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/medical-codes-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "medical-codes-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/medical-codes-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "medical-codes-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/medical-codes-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Refer to "your MCP client configuration file" generically — different clients use different config paths, and the server isn't client-specific.

Prerequisites

Bun v1.3 or higher (or Node.js v24+ — the server falls back to the better-sqlite3 optional dependency when not run under Bun).
No API key, account, or network access required.

Installation

Clone the repository:

git clone https://github.com/cyanheads/medical-codes-mcp-server.git

Navigate into the directory:

cd medical-codes-mcp-server

Install dependencies:

bun install

Configure environment (optional):

cp .env.example .env
# all runtime vars are optional — the server runs as-is

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`	Cap on rows returned by `medcode_search_codes` / `medcode_browse_hierarchy`.	`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_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

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 >100 MB, is not committed to git — fetch it from the GitHub Release assets or rebuild it locally with the build script. You only rebuild when refreshing to a new federal release. The script never downloads: extract the canonical .gov source files (ICD-10-CM/PCS order files, HCPCS ANWEB.txt — URLs in the script header) into a directory, then point the script at it:

bun run scripts/build-index.ts --from-dir <dir-with-source-files> --fy 2026

It parses the source files and emits the single .db file. It runs at build time only — the server never downloads anything.

Docker

docker build -t medical-codes-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio medical-codes-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/medical-codes-mcp-server. It copies the bundled data/medical-codes.db into the image so the server is fully self-contained. 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 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 and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MEDCODE_DB_PATH

Absolute path override for the bundled SQLite index. Defaults to the packaged data/medical-codes.db.

MEDCODE_MAX_RESULTSdefault 50

Cap on rows returned by search and browse tools (default 50, hard ceiling 200).

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "medical-codes-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/medical-codes-mcp-server@0.2.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "MEDCODE_DB_PATH": "<YOUR_MEDCODE_DB_PATH>",
        "MEDCODE_MAX_RESULTS": "50"
      }
    }
  }
}