[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_120":121},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module '@cyanheads/medical-codes-mcp-server' is not configured","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":26,"_34":-5,"_35":36,"_37":-5,"_38":-5,"_39":40,"_41":42,"_43":44,"_45":46,"_47":46,"_48":49,"_50":51,"_52":53,"_54":46,"_55":56,"_57":58,"_59":60,"_61":62,"_63":64,"_65":46,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":-5,"_77":-5,"_78":-5,"_79":46,"_80":-5,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94},"apiUrl","https://odel.app/api","creator","cyanheads","moduleId","medical-codes-mcp-server","@cyanheads/medical-codes-mcp-server","displayName","medical codes mcp server","tagline","Offline US medical code lookup and crosswalk — ICD-10-CM, ICD-10-PCS, HCPCS Level II. Keyless.","iconKey","https://avatars.githubusercontent.com/u/10339515?v=4","category","dev-tools","status","published","metaDescription","metaKeywords","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://medical-codes.caseyjhand.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781583623000,"updatedAt","sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.cyanheads%2Fmedical-codes-mcp-server","sourceVerified",true,"importedAt","upstreamStars",1,"upstreamUpdatedAt",1781561338000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/cyanheads/medical-codes-mcp-server","githubRepoFullName","cyanheads/medical-codes-mcp-server","releaseId","ext-cyanheads-medical-codes-mcp-server","version","0.1.3","descriptionMarkdown","

@cyanheads/medical-codes-mcp-server

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

6 Tools

\n\n

\n\n[![Version](https://img.shields.io/badge/Version-0.1.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/medical-codes-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/medical-codes-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n

\n\n

\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/medical-codes-mcp-server/releases/latest/download/medical-codes-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=medical-codes-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbWVkaWNhbC1jb2Rlcy1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22medical-codes-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/medical-codes-mcp-server%22%5D%7D)\n\n

\n\n

\n\n**Public Hosted Server:** [https://medical-codes.caseyjhand.com/mcp](https://medical-codes.caseyjhand.com/mcp)\n\n

\n\n

\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n

\n\n---\n\n> [!NOTE]\n> **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.\n\n## How it works\n\nThe 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.\n\nThat 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.\n\n### Bundled code systems\n\nOnly freely-redistributable, public-domain US federal code sets are bundled:\n\n| System | Source | Covers |\n|:---|:---|:---|\n| **ICD-10-CM** | [CDC/NCHS](https://www.cdc.gov/nchs/icd/icd-10-cm/index.html) — US federal, public domain | Diagnoses (billable leaf codes + non-billable category headers) |\n| **ICD-10-PCS** | [CMS](https://www.cms.gov/medicare/coding-billing/icd-10-codes) — US federal, public domain | Inpatient procedures (axis-based 7-character codes) |\n| **HCPCS Level II** | [CMS](https://www.cms.gov/medicare/coding-billing/healthcare-common-procedure-system) — US federal, public domain | Supplies, drugs, and non-physician services |\n\n**RxNorm** ([NLM](https://www.nlm.nih.gov/research/umls/rxnorm/), 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.\n\nCPT (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.\n\n**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.\n\n## Tools\n\nSix 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.\n\n| Tool | Description |\n|:---|:---|\n| `medcode_get_code` | Decode 1–50 codes to their official descriptions. Auto-detects the system per code; partial-success `found` / `notFound`. |\n| `medcode_search_codes` | Full-text search over official descriptions — go from a clinical description to the code. |\n| `medcode_check_code` | Validate a code's existence, currency, and billability, with a `whyNot` for non-billable/terminated cases. |\n| `medcode_map_codes` | Crosswalk a code within its hierarchy (`parents`/`children`); RxNorm drug directions land in a later release. |\n| `medcode_browse_hierarchy` | Walk a system's hierarchy for discovery without a search term. |\n| `medcode_list_systems` | List bundled systems with release identifiers, effective dates, and code counts (provenance). |\n\n### `medcode_get_code`\n\nDecode one or more codes seen in a claim, EHR field, or another health server's output. The 80% entry point.\n\n- Accepts 1–50 codes; mixed systems are fine — each code's system is detected independently from its shape\n- Partial success: resolved codes in `found`, unresolved in `notFound` with a per-code reason, so one bad code never fails the batch\n- An explicit `system` overrides auto-detection when a value is genuinely ambiguous (an ambiguous code lists its `candidateSystems`)\n- `includeHierarchy` attaches each code's parent and immediate children\n- The resolved `system` is echoed on every result for chaining into `medcode_map_codes` or a billability check\n\n---\n\n### `medcode_search_codes`\n\nFind codes whose official descriptions match a described concept — the reverse of `medcode_get_code`.\n\n- Every search term must appear (prefix-matched), so `\"diabetic neuropathy\"` returns codes mentioning both\n- Filter by `system`, `billableOnly` (exclude headers/categories), and `chapter`\n- Ranked by full-text relevance; results echo the resolved system per row\n- Discloses truncation when the result hits the cap, and returns an explicit notice (with the parsed query) when nothing matched\n\n---\n\n### `medcode_check_code`\n\nValidate whether a code is safe to submit, before a claim goes out.\n\n- Discriminated status: `valid_billable`, `valid_not_billable`, `valid_header`, or `terminated`\n- 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\")\n- 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`\n\n---\n\n### `medcode_map_codes`\n\nCrosswalk a code across systems and within a hierarchy.\n\n- 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)\n- 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\n- Every result carries `source` provenance (which system or edge answered) so a chained call uses the right identifier\n\n---\n\n### `medcode_browse_hierarchy`\n\nOrient in an unfamiliar system or enumerate a category's specific codes, without a search term.\n\n- With no `node`: top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values)\n- With a `node`: its immediate children\n- 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\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Typed per-tool error contracts — capable clients preview failure modes from `tools/list`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nDomain-specific:\n\n- Bundled SQLite + FTS5 index — offline, keyless, deterministic; no runtime network I/O, no rate limit\n- Code-shape auto-detection routes a code to its system; an explicit `system` disambiguates collisions\n- Real billable/validity signal from the source releases — the order-file billable flag drives `medcode_check_code`, not a heuristic\n\nAgent-friendly output:\n\n- 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\n- Graceful partial failure — `medcode_get_code` returns per-code `found` / `notFound` rows instead of failing the batch\n- Discriminated output contracts — `medcode_check_code`'s typed status and `medcode_map_codes`' `source` let callers branch on data, not string parsing\n\n## Getting started\n\nThis server ships with the code database bundled — there is no API key to obtain and nothing to download at runtime.\n\n### Public Hosted Instance\n\nA 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:\n\n```json\n{\n \"mcpServers\": {\n \"medical-codes-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://medical-codes.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-hosted\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"medical-codes-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/medical-codes-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"medical-codes-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/medical-codes-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"medical-codes-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/medical-codes-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\nRefer to \"your MCP client configuration file\" generically — different clients use different config paths, and the server isn't client-specific.\n\n### Prerequisites\n\n- [Bun v1.3](https://bun.sh/) or higher (or Node.js v24+ — the server falls back to the `better-sqlite3` optional dependency when not run under Bun).\n- No API key, account, or network access required.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/medical-codes-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd medical-codes-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment (optional):**\n\n```sh\ncp .env.example .env\n# all runtime vars are optional — the server runs as-is\n```\n\n## Configuration\n\nThe server is offline and keyless — there are no required variables. Two server-specific knobs and the standard framework vars apply:\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `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` |\n| `MEDCODE_MAX_RESULTS` | Cap on rows returned by `medcode_search_codes` / `medcode_browse_hierarchy`. | `50` (ceiling `200`) |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | Endpoint path where the MCP server is mounted. | `/mcp` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](https://github.com/cyanheads/medical-codes-mcp-server/blob/main/.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Building the bundled index\n\nThe bundled `data/medical-codes.db` is committed and shipped — you only rebuild it 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:\n\n```sh\nbun run scripts/build-index.ts --from-dir --fy 2026\n```\n\nIt parses the source files and emits the single `.db` file. It runs at build time only — the server never downloads anything.\n\n### Docker\n\n```sh\ndocker build -t medical-codes-mcp-server .\ndocker run --rm -e MCP_TRANSPORT_TYPE=stdio medical-codes-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/index.ts` | `createApp()` entry point — registers the six tools and opens the bundled index in `setup()`. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |\n| `src/services/code-index` | The code-index service — read-only SQLite handle, code-shape detection, FTS5 query translation. |\n| `scripts/build-index.ts` | Build-time ingest pipeline that bakes the federal source files into `data/medical-codes.db`. |\n| `data/medical-codes.db` | The bundled SQLite + FTS5 code index, opened read-only at runtime. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`/`AGENTS.md`](https://github.com/cyanheads/medical-codes-mcp-server/blob/main/CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging; the code index is a read-only global, not tenant state\n- Register new tools via the `createApp()` array in `src/index.ts`\n- 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\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](https://github.com/cyanheads/medical-codes-mcp-server/blob/main/LICENSE) for details.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Developer Tools","upstream",{"_97":98,"_99":100,"_101":102,"_103":104,"_105":106},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_95":82,"_96":82},"ratingAvg","reviewCount","topics",[107,108,109,19,110,111,112,113,114,115,116,117,118,119],"license","Apache-2.0","language","TypeScript","registryName","io.github.cyanheads/medical-codes-mcp-server","homepage","https://www.npmjs.com/package/@cyanheads/medical-codes-mcp-server","ai","ai-agents","bun","hcpcs","healthcare","icd-10","llm","mcp","mcp-server","medical-codes","medical-coding","model-context-protocol","typescript","ENV",{"_122":123,"_124":125,"_126":127},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]