medical-codes-mcp-server

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:

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.

Related MCP server: autoicd-mcp

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.

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:

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

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.