medical-codes-mcp-server

<div align="center"> <h1>medical-codes-mcp-server</h1> <p><b>Decode, search, validate, and crosswalk US medical codes — ICD-10-CM, ICD-10-PCS, HCPCS Level II — 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">

</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, public domain) — the drug-crosswalk layer (drug name ↔ RXCUI ↔ NDC, ingredients, brands) — is not bundled yet; it lands in a later release. Until then, medcode_map_codes' drug directions return a direction_unavailable error, and the hierarchy directions (parents/children) work today.

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); RxNorm drug directions land in a later release.
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
• 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 (available now): parents and children walk a code's prefix hierarchy (ICD-10-CM / HCPCS; ICD-10-PCS codes have no prefix parent)
• Drug directions (name_to_rxcui, ndc_to_rxcui, rxcui_to_ndc, rxcui_to_ingredients, rxcui_to_brands) are RxNorm-backed and return direction_unavailable until RxNorm is bundled in a later release
• 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 — each of the 7 characters is an independent axis, so browsing returns valid next-position axis values, not prefix children

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. Add the following to your MCP client configuration file.

{
  "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):

{
  "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:

{
  "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

1. Clone the repository:

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

2. Navigate into the directory:

cd medical-codes-mcp-server

3. Install dependencies:

bun install

4. 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 is committed and shipped — you only rebuild it when refreshing to a new federal release:

bun run scripts/build-index.ts

The script downloads the canonical .gov source files, parses them (ICD-10-CM/PCS order files, HCPCS ANWEB.txt), 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.