medical-codes-mcp-server

---

说明

仅供参考，不构成临床或编码建议。 此服务从公有领域的联邦版本中返回官方代码说明和可计费／有效性标记，帮助你解码和查询代码。它不是医疗建议，valid_billable 结果也不代表编码或报销决定。提交索赔前，请务必根据官方版本（CMS、CDC/NCHS、NLM）和付款方规则核实代码。捆绑数据的时效仅与构建时纳入的版本一致 — 调用 medcode_list_systems 查看当前启用的具体版本。

概述

美国医学代码 — ICD-10-CM、ICD-10-PCS、HCPCS Level II，以及包含 RxClass 药物类别的 RxNorm — 可通过官方联邦版本离线搜索。可解码、搜索、检查可计费性，并交叉映射代码、药物、NDC 和药物类别。

工具

工具	描述
medcode_get_code	将 1–50 个代码解码为其官方描述。自动检测每个代码所属的体系；支持部分成功，返回 found / notFound。
medcode_search_codes	对官方描述进行全文搜索——从临床描述查找对应代码。
medcode_check_code	验证代码是否存在、是否有效以及能否计费；对于无法计费或已终止的情况，提供 whyNot。
medcode_map_codes	在代码的层级结构中进行交叉映射（parents/children）；跨 RxNorm 映射药物（名称 ↔ RXCUI、NDC ↔ RXCUI、RXCUI → 成分/品牌）；或将药物映射到其 RxClass 类别，并将类别映射到其成员药物。
medcode_browse_hierarchy	遍历某个体系的层级结构，无需搜索词即可探索。
medcode_list_systems	列出内置体系及其发布标识、有效日期和代码数量，以及 RxClass 层中各来源的版本（溯源信息）。

工作原理

仅内置可自由再分发的美国联邦公有领域代码集；在软件包构建时将其预先写入单个 SQLite + FTS5 数据库，并在启动时以只读模式打开。

内置代码体系

系统	来源	覆盖范围
ICD-10-CM	CDC/NCHS — 美国联邦数据，属于公共领域	诊断（可计费的叶级代码和不可计费的类别标题）
ICD-10-PCS	CMS — 美国联邦数据，属于公共领域	住院治疗操作（基于轴的 7 位字符代码）
HCPCS Level II	CMS — 美国联邦数据，属于公共领域	用品、药物和非医师服务
RxNorm	NLM RxNav — 公共领域	药物：名称 ↔ RXCUI、NDC ↔ RXCUI 对照关系、成分和品牌
RxClass 药物类别	NLM RxClass — 仅限美国政府来源	RxNorm 药物的类别：药理类别、作用机制、生理效应、药代动力学、治疗类别、化学结构、治疗或预防的疾病及禁忌症、VA 类别、DEA 管制等级、CVX 疫苗代码

RxNorm 内置当前的标准化药物词汇——成分、品牌名称、临床药物和品牌药物，以及药品包装，并包含其 NDC 和成分/品牌对照关系；这些数据在构建时通过无需密钥的 RxNav REST API 获取，该 API 仅提供属于公共领域的标准化数据层。我们特意排除需遵循 UMLS 许可的完整 RxNorm 发行版，以确保该软件包可以自由再分发。

RxClass 是这些药物的类别层，而非代码体系：包含 20,723 个类别和 87,269 条药物—类别关系，在构建时通过无需密钥的 RxClass API 获取。软件包内置 6 个来源，且全部为美国政府作品：MEDRT（VA MED-RT——作用机制、生理效应、药代动力学、化学结构和疾病关系）、FDASPL（FDA 结构化产品标签中的既定药理类别及相关类别）、FMTSME（治疗类别）、VA（VA 国家处方集类别）、RXNORM（DEA 管制物质等级）和 CDC（CVX 疫苗代码）。以下 4 个来源未纳入：ATC 和 ATCPROD，其 WHO 条款禁止为商业目的复制和分发；SNOMEDCT，受 SNOMED CT 关联方许可约束；以及 DAILYMED，其关系数据与 FDASPL 几乎完全相同（8,710 条中有 8,696 条相同），且未发布版本信息。

本产品使用了美国国家医学图书馆（NLM）、美国国立卫生研究院、美国卫生与公众服务部提供的公开数据；NLM 不对本产品负责，也不为本产品或任何其他产品背书或提供推荐。

CPT（AMA 版权所有）和 SNOMED CT / LOINC（受 UMLS 许可限制）特意未纳入——这些内容不能自由再分发，因此无法随离线软件包一同提供。

美国范围。 ICD-10-CM 和 ICD-10-PCS 是美国的临床修订版，并非 WHO ICD-10/ICD-11 基础版本或其他国家的国家修订版。

功能参考

medcode_get_code _工具

• 接受 1–50 个代码；可以混用系统——每个代码的系统都会根据其格式独立检测
• 直接将国家药品代码（NDC）解码为其 RxNorm 产品——支持带连字符的 FDA 分段配置（4-4-2、5-3-2、5-4-1 或 11 位的 5-4-2）以及不带连字符的 10/11 位数字；通过随附的 NDC↔RxNorm 映射离线解码，并标记为 source: "NDC"
• 部分成功：已解析的代码列在 found 中，未解析的代码列在 notFound 中，并附有逐代码说明——若某个裸整数无法解析为任何结果，会将其标为可能的 CPT / HCPCS Level I 代码（不在支持范围内）；但裸 10/11 位数字除外，此时会将其标为没有任何随附药品映射的 NDC
• 采用带点号的 ICD-10-CM 格式（A01.00）书写的代码会解析为 ICD-10-CM；值确实存在歧义时，显式指定的 system 会覆盖自动检测（歧义代码会列出其 candidateSystems），并跳过 NDC 解码；includeHierarchy 会为每个代码附加其父级和直接子级
• alsoInSystems 会列出包含相同代码字符串的其他随附系统——该代码在每个系统中都是不同的代码
• RxNorm 行的 billable: null（RxNorm 没有计费概念），且 shortDescription: null（RxNorm 只发布一个名称）；chapter 表示 RxNorm 术语类型（IN、SCD、SBD 等）
• 错误：当所有请求的代码都存在于多个随附系统中且未提供 system 时，返回 ambiguous_system，并在 candidateSystems 中列出这些系统的并集；当请求的代码均未解析成功时，返回 no_codes_found，无论是在任何随附系统中，还是在显式指定的 system 中——同时会指出包含任一代码的其他随附系统，以及存在于多个系统中的每个代码

---

medcode_search_codes _工具

• 每个搜索词都必须出现——先按词元前缀匹配，再按子字符串匹配，因此也会找到词形变化和复合形式；RxNorm 概念仅按药品名称匹配，绝不按术语类型匹配
• 按 system、billableOnly（排除标题/类别、已终止的 HCPCS 代码以及所有 RxNorm 概念——RxNorm 没有计费概念）和 chapter（对 RxNorm 而言即术语类型）筛选
• 按全文相关性排序；每行结果都会显示解析后的 system
• 通过 cursor/limit 分页（默认值为 MEDCODE_MAX_RESULTS，上限为 200）；会提供 truncated/nextCursor，无匹配结果时会返回包含已解析查询的提示

---

medcode_check_code _工具

• 区分型 status：valid_billable、valid_not_billable、valid_header、valid 或 terminated——valid 表示当前有效的 RxNorm 概念，返回的 billable: null 是因为 RxNorm 没有计费概念
• whyNot 说明不可计费或已终止的情况——不可计费或已终止的代码属于成功结果，而非错误
• HCPCS 代码在其终止日期（CMS 允许其用于理赔的最后一天）过去后即为 terminated；根据调用时的 UTC 日期判断；在此之前会检查为可计费，并在 whyNot 中注明该日期
• 采用带点号的 ICD-10-CM 格式（A01.00）书写的代码会解析为 ICD-10-CM；alsoInSystems 会列出包含相同代码字符串的其他随附系统，因为判定仅适用于解析出的系统
• 错误：unknown_code（代码不存在于指定系统中；未指定 system 时，则表示代码不存在于任何随附系统中，并会列出该代码格式符合的所有系统；带点号的 ICD-10-CM 格式仅列出 ICD-10-CM——若显式指定了 system，而代码存在于其他随附系统中，则会将其标为该系统的代码；NDC 也会归入此错误，包括格式正确但没有任何随附药品映射的裸 10/11 位数字，并提供指向 medcode_get_code 和 medcode_map_codes ndc_to_rxcui 的恢复建议）以及 ambiguous_system（代码存在于多个系统中，且未指定 system）

medcode_map_codes _工具

• 层级方向 parents/children 每次调用仅遍历一层（深度为 1）；ICD-10-PCS 代码没有前缀父级，RxNorm 概念没有代码层级
• 药物方向（RxNorm）：name_to_rxcui（匹配药物名称，不匹配术语类型）、ndc_to_rxcui/rxcui_to_ndc（NDC 可采用 FDA 分段配置中的连字符格式——4-4-2、5-3-2、5-4-1 或 11 位的 5-4-2——也可使用不带连字符的 10/11 位数字）、rxcui_to_ingredients/rxcui_to_brands（每条命中结果都带有 conceptType：IN/PIN/MIN/BN）
• 药物类别方向（RxClass）：rxcui_to_classes 返回一个 RXCUI 的类别，class_to_rxcuis 返回一个类别 ID 的直接成员 RXCUI；每条结果都带有其 RxNorm 名称和 conceptType。每条命中结果都带有 classType、source（声明该类别的 RxClass 来源）和 relation（has_epc、may_treat，等等）——每个类别 × 来源 × 关系各有一条结果。以 ci_ 开头的关系（ci_with、ci_moa、ci_pe、ci_chemclass）表示禁忌，而非适应症
• RxClass 将大多数类别关联到成分，因此药物产品也会返回其成分的类别，并在 via 中标明成分（其 IN 对应 PIN）；继承只向上进行。DEA 管制等级仅记录在药物产品上，VA 类别也几乎只记录在药物产品上：要查询这些信息，请映射产品——成分返回空的 SCHEDULE 或 VA 结果，表示该信息记录在产品上，而非表示未列入管制等级或未分类。成员关系为直接关系：如果某类别的所有药物都关联到其子类别（N0000193873 “利尿剂”），则该类别不会返回成员，且不会遍历类别层级
• 类别 ID 匹配时不区分大小写；单个数字的 CVX 疫苗代码会被识别为补零后的 ID（3 是 CVX 03）
• classType（EPC、MOA、PE、PK、TC、CHEM、DISEASE、VA、SCHEDULE、CVX）可缩小两个类别方向的范围，在其他所有方向中都会被拒绝
• children、name_to_rxcui、rxcui_to_ndc、rxcui_to_classes 和 class_to_rxcuis 通过 cursor/limit 分页——一个 RXCUI 可能对应数千个包装 NDC，一个类别也可能有数千名成员；其他所有方向都会拒绝 limit 和 cursor，而 system 仅对 parents/children 起作用（药物和类别方向只接受 RXNORM）
• 每条命中结果都带有 source 来源信息，以便链式调用使用正确的标识符；如果来源可解析，但在请求的方向上没有关联，则会成功返回空结果并附带提示，而非报错——例如，品牌名称没有类别
• 错误：no_mapping（来源无法解析——例如将代码系统名称作为 from 传入；在应传入代码或 RXCUI 的位置传入 NDC；传入格式正确但没有内置药物映射的 NDC（ndc_to_rxcui 的表述会说明这一点）；在应传入 RXCUI 的位置传入类别 ID；或传入可能属于范围外 CPT / HCPCS Level I 代码的裸整数。对于这些情况，系统会相应说明，并将代码系统名称还原为该方向所需的唯一输入；如果 parents/children 代码不属于显式指定的 system，则会指出包含该代码的内置系统名称；如果 rxcui_to_* 的来源属于其他内置系统，则会指出该系统的代码，因为这些方向仅读取 RxNorm 概念；ndc_to_rxcui 未命中时会说明输入格式是否错误，或格式正确但没有内置药物映射；class_to_rxcuis 未命中时会按类别 ID 的情况措辞，并指出误传的 RXCUI 或类别类型）、field_not_applicable（该方向不使用的 system、classType、limit 或 cursor）、direction_unavailable（此构建中未包含 RxNorm，或类别方向未包含 RxClass 层）、ambiguous_system

medcode_browse_hierarchy _工具

• 不提供 node：返回顶级条目（ICD-10-CM 类别、HCPCS 范围分组、ICD-10-PCS 第一轴取值）；提供 node：返回其直接子项
• ICD-10-CM/HCPCS 使用前缀层级结构；ICD-10-PCS 按轴组织，只能浏览顶级 Section 轴——位置 2–7 取决于上下文，无法从不完整的平面代码中枚举
• 通过 cursor/limit 分页（默认值为 MEDCODE_MAX_RESULTS，上限为 200）
• 错误：节点不存在时返回 unknown_node；对于 ICD-10-PCS，如果节点包含字母表外字符或开头没有任何已打包代码，也会返回该错误

---

medcode_list_systems _工具

• 无输入；为每个已打包系统返回一条条目，包含 releaseId、effectiveStart/effectiveEnd、codeCount、sourceUrl 和 builtAt
• builtAt 标记系统数据的日期：对于 ICD-10-CM、ICD-10-PCS 和 HCPCS，表示根据指定版本构建索引的时间；对于没有发布版本标签的 RxNorm，表示获取 RxNav 快照的日期，因此从同一快照重新构建会报告相同日期
• classLayer 单独报告 RxClass 层（与代码系统分开）：包含其类别和边的数量，以及每个来源的 RxClass 版本（RxClass 未发布版本的来源为 null——CDC）、该来源贡献的类别和边的数量，以及获取 RxClass 快照的日期；不包含该层的构建中此项为 null
• 确认当前运行的构建中准确包含哪个 ICD-10-CM/PCS 财年、哪个 HCPCS 版本、哪个 RxNorm 快照和哪些 RxClass 来源

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志和可选的 OpenTelemetry 跟踪。

ICD-10 / HCPCS / RxNorm 专属功能：

• 内置 SQLite + FTS5 索引——离线、无需密钥、结果确定；运行时无需网络 I/O，也没有速率限制
• 自动检测代码格式并将代码路由到相应系统；点分格式的 ICD-10-CM 代码会解析为 ICD-10-CM；显式指定 system 可消除歧义
• 直接采用源版本中的真实可计费/有效性信号——medcode_check_code 根据 order-file 的可计费标志，以及 HCPCS 代码相对于调用日期的终止日期进行判断，而非使用启发式方法；RxNorm 没有计费概念，因此报告 billable: null，而不是给出判断结果

便于 Agent 使用的输出：

• 每个响应均包含来源信息——回传解析后的 system 以便链式调用；如果某个代码字符串在另一个已打包系统中含义不同，则通过 alsoInSystems 标记；medcode_list_systems 会准确报告构建中包含的版本
• 优雅处理部分失败——medcode_get_code 会为每个代码返回 found/notFound 条目，而不是导致整个批次失败
• 使用可区分的输出契约——medcode_check_code 的类型化 status 和 medcode_map_codes 的 source 让调用方可以依据数据分支，而不必解析字符串

开始使用

此服务内置代码数据库，无需获取 API 密钥，也无需在运行时下载任何内容。

公共托管实例

公共实例位于 https://medical-codes.caseyjhand.com/mcp——无需安装。该实例提供 Streamable HTTP；不同客户端使用各自的配置格式。

对于 Claude Code：

claude mcp add --transport http medical-codes-mcp-server https://medical-codes.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

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

对于 Cursor（mcp.json）：

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

Claude Desktop 可在“设置”→“连接器”中添加远程服务。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

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

或使用 npx（无需 Bun）：

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

或使用 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"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

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

此处的“你的 MCP 客户端配置文件”是泛指——不同客户端使用不同的配置路径，而且此服务并非专属于某个客户端。

前置条件

• Bun v1.4 或更高版本（或 Node.js v24+ — 未在 Bun 下运行时，服务会回退到可选依赖 better-sqlite3）。
• 无需 API 密钥、账户或网络访问权限。

安装

1. 克隆仓库：

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

2. 进入目录：

cd medical-codes-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

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

配置

该服务离线运行且无需密钥 — 不需要任何变量。适用两个服务专属配置项和标准框架变量：

变量	说明	默认值
MEDCODE_DB_PATH	捆绑的 SQLite 索引的绝对路径覆盖值。仅在指向自建或外部挂载的数据库时设置。	打包内的 data/medical-codes.db
MEDCODE_MAX_RESULTS	调用未发送 limit 时的默认分页大小 — 适用于 medcode_search_codes、medcode_browse_hierarchy 和分页的 medcode_map_codes 方向 — 以及 medcode_get_code 在设置 includeHierarchy 时附加的子项数量。	50（上限为 200）
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话处理方式：stateless、stateful 或 auto（解析为 stateful）。src/index.ts 声明为 stateless — 没有工具会在调用过程中要求调用方提供输入 — 此变量会覆盖该声明。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用的参数和结果（仅对键名进行脱敏），记录长度受 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 限制。	false
OTEL_ENABLED	启用 OpenTelemetry 监测。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 基础 URL；跟踪数据导出到 /v1/traces，指标导出到 /v1/metrics。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	选择启用 OTLP 日志导出；基础端点不会启用此功能。	—

可选覆盖项的完整列表，请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

构建捆绑索引

捆绑的 data/medical-codes.db 随 npm 包和 Docker 镜像一起发布，但由于大小超过 100 MB，不会提交到 git。如需获取预构建副本而不重新构建，可从 npm 包中获取（data/medical-codes.db），也可从每个 GitHub Release 附带的 medical-codes-mcp-server.mcpb 捆绑包中获取 — 这是一个 zip 归档，其中的索引位于 data/medical-codes.db。只有在更新到新的联邦版本时才需要重新构建。构建脚本不会下载任何内容：将规范的 .gov 源文件（ICD-10-CM/PCS 订单文件，以及采用 CMS 文件名的 HCPCS 季度 ANWEB 文件，该文件名会设置 HCPCS 版本标签 — URL 见脚本头部）解压到一个目录中，然后使用两个获取器将 RxNorm 和 RxClass 缓存到该目录中（目标目录须为空：两个获取器都会续用已有缓存，而非重新获取），最后将该目录传给脚本：

bun run scripts/ingest/fetch-rxnav.ts --out <dir>/rxnav        # RxNorm, from the keyless RxNav API
bun run scripts/ingest/fetch-rxclass.ts --rxnav <dir>/rxnav --out <dir>/rxclass   # RxClass, after RxNorm
bun run scripts/build-index.ts --from-dir <dir> --fy 2027       # --fy labels the ICD-10-CM/PCS releases

脚本会解析源文件和缓存，并生成单个 .db 文件。RxNorm 的日期取其 RxNav 获取完成的时间，RxClass 源文件的日期则取其各自获取完成的时间；这些日期都会记录在缓存中，因此使用相同缓存重新构建时报告的日期也相同。构建仅在构建时运行 — 服务绝不会下载任何内容。

Docker

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

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/medical-codes-mcp-server。它会将捆绑的 data/medical-codes.db 复制到镜像中，使服务完全自包含。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册六个工具，并在 setup() 中打开捆绑的索引。
src/config	使用 Zod 解析和验证服务专用的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/services/code-index	代码索引服务——只读 SQLite 句柄、代码格式检测、FTS5 查询转换。
scripts/build-index.ts	构建时的数据导入流程，将联邦源文件打包到 data/medical-codes.db。
data/medical-codes.db	捆绑的 SQLite + FTS5 代码索引，运行时以只读方式打开。
tests/	与 src/ 对应的单元测试和集成测试。

开发指南

请参阅 CLAUDE.md/AGENTS.md，了解开发指南和架构规则。简要来说：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志；代码索引是只读全局数据，而非租户状态
• 通过 src/index.ts 中的 createApp() 数组注册新工具
• 捆绑的 DB 是事实来源——根据源发布内容展示真实的可计费/有效性标记；绝不伪造代码或可计费性判断

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。