npi-providers-mcp-server

---

概述

来自 NPI Registry 的美国医疗服务提供者目录。通过自然语言按姓名、地点和专业搜索医生和机构，将任意 NPI 解码为对应的服务提供者记录，并浏览 NUCC 专业分类法。

工具

工具	描述
npi_search_providers	按姓名、机构、地点、服务提供者类型和专业搜索 NPPES 注册表。自然语言描述的专业会先通过内置的 NUCC 分类法解析，再进行搜索。
npi_get_provider	获取最多 10 个 NPI 对应的 NPPES 专业执业记录，包括分类、执业地址、资质、标识符、端点和状态。个人服务提供者仅保留 LOCATION 地址行。
npi_lookup_taxonomy	解析、获取或浏览 NUCC 医疗服务提供者分类法——完全离线。

资源

资源	描述
npi://provider/{npi}	按 NPI 获取单个服务提供者的解码记录——对应 npi_get_provider 的资源版本。
npi://taxonomy/{code}	按代码获取单个 NUCC 分类条目——对应 npi_lookup_taxonomy 的 get 模式资源版本。

所有资源数据也可以通过工具访问；这些资源是面向支持资源的客户端提供的便捷对应项。

内置的 npi-providers-guide 技能可通过 skill://npi-providers-guide/SKILL.md 获取。它介绍专业类别、服务提供者身份以及穷尽式目录搜索的局限性。

功能参考

npi_search_providers _工具

• 输入：name_search 或 first_name / last_name（个人）、organization_name（组织）、provider_type、city / state / postal_code（仅限执业地址），以及通过内置 NUCC 分类体系解析的自然语言 specialty，或精确的 taxonomy_description（两者不可同时使用）。至少需要一个条件；仅提供州会被拒绝；个人条件与组织条件不能混用。尾随的 * 前至少需要 2 个字符；postal_code 可接受 5 位或 9 位数字，或以 * 结尾的 2–9 位前缀。limit 必须为正数（上限为 200，默认值为 10），skip 范围为 0–1000。可选的 use_first_name_alias 用于控制上游系统的名字变体；未提供时，非通配符名字默认启用。对于通配符搜索或未提供名字的搜索，若提供此选项，系统会报告该选项不适用
• 输出：紧凑的行（npi、姓名、主要分类、主要执业地点的 city / state / postalCode、status），其中 matchedLocation / matchedOtherName 指明匹配到的执业地点或其他名称，resolvedTaxonomies / appliedTaxonomyDescription 回显专业分类的解析结果。只有在名字非通配符时，appliedFirstNameAlias 才会报告实际生效的布尔值。不报告真实总数：完整的一页会提供 nextPage；在窗口末端（skip 为 1000、limit 为 200）会返回用于继续搜索的 continuationPostalCodes
• 类型化错误原因：no_search_criteria、conflicting_specialty、mixed_provider_criteria、unresolved_specialty、invalid_search_field

---

npi_get_provider _工具

• 接受 npis：单个 NPI 或最多 100 个原始条目，每个条目恰好为 10 位数字。去重并检查每个校验位，然后查询前 10 个不同的有效 NPI；可选的 unprocessed 会按顺序列出其余有效 NPI。若 NPI_CLAMP_LIMITS=false，原始数组最多只能包含 10 个条目
• 将批次划分为 found（已解码记录：含许可证信息的分类、执业地址、资质、标识符、FHIR/Direct 端点、状态——个人服务提供者仅包含 LOCATION 地址行，因此不会返回其邮寄地址）、notFound（确认不存在）、errored（上游失败——请重试这些条目）和 invalid（校验位错误，绝不查询）
• 类型化错误原因：invalid_npi_format（所有 NPI 的校验位均错误）、none_found（查询的所有 NPI 均确认不存在）；上游失败会直接显示对应的底层错误。错误消息和结构化错误数据会保留所有无效 NPI 及任何未处理的剩余条目

---

npi_lookup_taxonomy _工具

• 模式：resolve（将 query 解析为匹配的有效代码）、get（根据精确的 code 返回包含 NUCC notes 的完整条目）、browse（逐层浏览 grouping → classification → specialization，可按 grouping 和 NUCC section 筛选）。Section 描述分类体系类别，而非服务提供者的 NPI 实体类型；如需指定实体类型，请使用搜索的 provider_type。resolve / browse 接受正数 limit（上限为 50，默认值为 20）和 skip（0–1000），并会说明是否已截断（truncated）；应用默认值之前会先拒绝错误模式的参数
• 每个条目都带有 status（active / inactive），非有效代码还会包含 replacedBy；resolve 不包含非有效代码，而 get 和 browse 会返回这些代码。已解析条目的 specialization（若不存在，则为 classification）是 npi_search_providers.taxonomy_description 接受的精确值
• 定义和注释会将 NUCC HTML 标记转换为易读的换行和列表项目符号；字面标记和源文本保持不变
• 类型化错误原因：no_match、missing_argument、wrong_mode_argument

---

npi://provider/{npi} _资源

• 对于单个 NPI，以 application/json 格式返回与 npi_get_provider 相同的解码记录 — 个人提供者只保留 LOCATION 地址行
• npi 必须是格式正确的 10 位 NPI；若未通过 NPI 校验位检查，则返回 invalid_npi_format（不会请求注册表）；若注册表中没有记录（已停用或从未分配），则返回 no_record

---

npi://taxonomy/{code} _资源

• 以 application/json 格式返回与 npi_lookup_taxonomy 的 get 模式相同的条目（包括 NUCC 的 notes、status 和 replacedBy；停用代码仍可读取）；公开缓存 24 小时
• code 必须匹配 ^\d{3}[A-Z0-9]{6}X$；若不存在该代码的条目，则返回 no_match

功能

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

NPI/NPPES 专属功能：

• 无需密钥 — 直接调用公开的 CMS NPPES NPI Registry API（v2.1），无需 API 密钥或账户
• 内置 NUCC 分类体系 — 镜像中包含 883 个代码的 Healthcare Provider Taxonomy（v26.1），启动时会加载到内存索引，因此专业领域解析和代码查询完全离线可用，无需依赖第二个上游服务
• 专业领域解析会将模糊术语（“心脏科医生”）转换为注册表筛选所用的精确分类描述，并返回匹配结果供 Agent 验证
• 检测注册表验证失败时返回 HTTP 200 并在响应正文中包含 Errors[] 的特殊行为，并将其映射为可恢复的类型化错误原因

便于 Agent 使用的输出：

• 搜索溯源 — 返回已解析的分类体系和发送给注册表的准确 taxonomy_description，让 Agent 清楚实际搜索了什么，并可使用不同代码重新搜索
• 真实分页 — 返回的数量表示页面大小，绝不伪造总数；结果达到整页时会明确给出下一页页码；宽泛查询达到可访问的 1200 条结果上限时，会提供后续查询所需的邮政编码前缀
• 优雅处理部分失败 — npi_get_provider 会为每个 NPI 返回 found / notFound / errored / invalid 状态行，而不会导致整个批次失败

开始使用

连接到托管实例，无需安装：

claude mcp add --transport http npi-providers-mcp-server https://npi-providers.caseyjhand.com/mcp

也可以在本地运行：

claude mcp add npi-providers-mcp-server -- npx -y @cyanheads/npi-providers-mcp-server

对于其他客户端，请将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "npi-providers-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/npi-providers-mcp-server"]
    }
  }
}

无需 API 密钥。Docker 或从源码构建的说明请参阅运行服务。

配置

无需设置必需变量——该服务开箱即用，可直接访问无需密钥的 NPPES 注册库。以下变量均为可选覆盖项。

变量	描述	默认值
NPPES_API_BASE_URL	NPPES NPI 注册库 API 基础 URL。可覆盖为私有镜像或用于测试。	https://npiregistry.cms.hhs.gov/api
NPPES_TIMEOUT_MS	NPPES 请求的单次 HTTP 超时时间，单位为毫秒。	15000
NPI_CLAMP_LIMITS	将搜索限制钳制为 200、分类限制钳制为 50；接受 100 个原始 NPI，同时查找 10 个不同的有效 NPI。设为 false 时，恢复架构上限：200、50 和 10 个原始 NPI。每次实际钳制都会发出通知、日志和计数器事件。	true
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	认证模式：none、jwt 或 oauth。	none
MCP_SESSION_MODE	HTTP 会话处理模式：stateless、stateful 或 auto。此服务固定使用 stateless；架构默认值 auto 会解析为 stateful。	stateless
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败工具调用的参数和结果，按键名进行脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节（默认值为 16384）。自由格式值中的机密不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 监测（跨度、指标、完成日志）。	false

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

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。NPPES 注册库无需密钥，NUCC 分类数据已打包。

• 克隆并安装：

  git clone https://github.com/cyanheads/npi-providers-mcp-server.git
  cd npi-providers-mcp-server && bun install
  cp .env.example .env   # optional NPPES base URL and timeout overrides
  

• 构建并运行：

  # 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
  

Docker

docker build -t npi-providers-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 npi-providers-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/npi-providers-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时添加 --build-arg OTEL_ENABLED=false 即可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/nppes	NPPES NPI 注册库 API 客户端——构建查询、检测 HTTP 200 响应中的 Errors[]、进行规范化处理。
src/services/taxonomy	已打包的 NUCC 分类服务——用于解析、获取和浏览的内存索引。
skills/	已发布的 Agent 指南，随软件包一同提供，并通过 MCP 交付。
tests/	与 src/ 结构相对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简而言之：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围内的日志记录，使用 ctx.state 进行租户范围内的存储
• 在 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失字段

数据归属

提供方数据来自 CMS NPPES NPI Registry（公有领域）。随附的专业代码来自 NUCC Health Care Provider Taxonomy，由 American Medical Association 代表 National Uniform Claim Committee (NUCC) 享有 © 版权；除格式调整外，均未修改，并根据 NUCC 许可重新分发。请参阅 NOTICE。

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。