medical-codes-mcp-server

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

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

Related MCP server: Medical Terminologies 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

• 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:

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

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

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.