npm Registry MCP Server

@yawlabs/npmjs-mcp

点击一次，即可将其添加到本地 Yaw MCP 配置中，让它在每个 Yaw Terminal 会话中都可用。也可以在下方手动安装。

可通过 Claude Code、Cursor 和任何 MCP 客户端执行 npm registry 操作。 提供 64 个工具，覆盖完整的 registry 功能：软件包情报、安全审计、依赖分析、组织／团队管理，以及通常难以在本地执行的写入操作（npm deprecate、npm dist-tag、npm owner、npm unpublish）。

由 Yaw Labs 构建并维护。

为什么选择它？

其他 npm MCP 服务只是封装了 npm search，然后就此打住。它可不止于此。

• 完整的 registry HTTP 接口 — 64 个工具涵盖读取、写入、组织、团队、钩子、来源证明、可信发布者和运维健康状况。不只是 npm view。
• 能在 Agent 中正常运行的写入操作 — npm_deprecate、npm_undeprecate、npm_dist_tag_set、npm_unpublish_version 会使用支持绕过 2FA 的细粒度访问令牌，直接调用 HTTP API。无需 2FA 提示、无需查找 --otp，也不会因绑定会话的 .npmrc 而遭遇 ENEEDAUTH。（自 2026-07-31 起，即使启用了 2FA 绕过，npm 仍要求对所有者、访问权限、团队成员资格和授权，以及组织成员资格和令牌变更进行交互式 2FA 验证；对于这些工具，错误信息会指出用户应运行的确切 npm 命令。）
• 针对 Agent 的失败处理 — npm_check_auth 和 npm_publish_preflight 会检测非交互式上下文，并返回可供用户运行的命令；每个写入错误都会说明发送了什么内容以及对应的 npm CLI 命令，而不是对无法恢复的错误反复重试。
• 默认安全 — npm_unpublish_* 要求设置 confirm: true。npm_owner_remove 会阻止你把自己锁在账户之外。npm_deprecate 会在发送前拒绝超出 registry 1024 个字符限制的消息。
• 内置运维操作手册 — npm_ops_playbook 会返回规范的工具与 CLI、CI 决策矩阵，让你的 Agent 一开始就选对路径。
• 工具注解 — 每个工具都会声明 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint，让 MCP 客户端可以跳过安全操作的确认步骤。
• 读取操作无需 API 密钥 — 搜索、软件包、下载量、安全、依赖树和许可证均可匿名使用。通过 NPM_TOKEN 可选择启用身份验证。
• 即时启动 — 以单个打包文件的形式发布，运行时零依赖。无需花 5 分钟安装 node_modules。
• 输入强化 — 软件包名称、作用域、版本、dist-tag 和团队名称均会根据 npm 的实际限制进行正则验证。可防范 URL 构造中的 CRLF 和路径遍历攻击。

快速开始

1. 在项目根目录中创建 .mcp.json

macOS / Linux / WSL：

{
  "mcpServers": {
    "npm": {
      "command": "npx",
      "args": ["-y", "@yawlabs/npmjs-mcp@latest"]
    }
  }
}

Windows：

{
  "mcpServers": {
    "npm": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/npmjs-mcp@latest"]
    }
  }
}

为什么 Windows 上要多一步？ 从 Node 20 开始，child_process.spawn 无法直接执行 .cmd 文件（Windows 上的 npx 就是这种文件）。使用 cmd /c 包装是标准的解决方法。

2. 重启并批准

重启 Claude Code（或你的 MCP 客户端），并在出现提示时批准 npm MCP 服务。

3. （可选）添加 npm 令牌以执行写入操作

只读工具无需任何设置即可使用。对于写入工具（deprecate、dist-tag、owner、team_*、org_member_*、unpublish、hook_*、access_set*、token_revoke），请在 env 块中添加 NPM_TOKEN：

{
  "mcpServers": {
    "npm": {
      "command": "npx",
      "args": ["-y", "@yawlabs/npmjs-mcp@latest"],
      "env": {
        "NPM_TOKEN": "npm_xxxxxxxxxxxx"
      }
    }
  }
}

使用细粒度访问令牌，并将权限范围限定为你希望 Agent 管理的包和组织。

就这样。现在可以向你的 AI 助手提问：

“弃用 my-old-pkg 1.x，并指向 v2”

“fastify 的依赖树向下展开三级是什么样的？”

“审查 express 是否存在已知 CVE，并告诉我如何修复”

“next.js 的维护者有哪些？他们每个人上次发布是什么时候？”

配置

环境变量	默认值	描述
NPM_TOKEN	（无）	npm 访问令牌。仅写入、身份验证、组织、访问权限和钩子工具需要此令牌。请使用细粒度访问令牌（用于无头写入时启用 2FA 绕过）；包括 Automation 令牌在内的经典令牌已于 2025 年 12 月撤销。
NPM_REGISTRY	https://registry.npmjs.org	替代注册表（企业／私有）。必须支持 npm HTTP API 格式。
NPM_REQUEST_TIMEOUT_MS	30000	每次注册表请求尝试的超时时间，单位为毫秒，包括读取响应正文的时间。读取操作遇到超时、网络错误或 HTTP 429／502／503／504 时会重试，总共最多尝试 3 次，因此读取停滞时耗时可能约为此值的 3 倍。写入操作遇到超时或网络错误后绝不会重新发送，因为注册表可能已经应用了该操作；只有遇到 429／503 时才会重试。非正数或非有限数值（包括 Infinity）会回退到默认值，因此无法关闭超时。
NPM_RETRY_BACKOFF_MS	500	重试前的基础等待时间，每次加倍：默认依次为 500 ms、1000 ms。如果重试响应包含 Retry-After 标头，则改用该等待时间（上限为 30 s），与此变量的设置无关。0、空值或空白字符会取消退避等待。其他负数或非数值会回退到默认值。
DEBUG	（无）	每次 npm API 调用尝试都会向 stderr 写入一行日志，前缀为 [npmjs-mcp]：包含方法、URL，然后是状态码和收到响应标头所用的毫秒数，或重试前的等待时间和尝试次数，或网络错误。绝不会记录令牌。只有值精确为 npmjs-mcp 或 * 时才会启用；其他值（例如 1 或 npmjs-mcp:*）均会被忽略。为其他工具设置的 DEBUG=* 也会启用此项。
NPMJS_MCP_RUNTIME	auto	auto：如果启动器当前运行在 oam 上，且版本为 0.18.0 或更高，则在该 oam 上提供服务；否则使用能找到的最新 0.18.0 或更高版本的 oam 二进制文件（参见 OAM_BIN）；再否则使用 Node。低于 0.18.0 的 oam 主机绝不会自行提供此服务——它会转交给最新可用的 oam、PATH 上的 Node，或者在两者都不存在时退出并报错。不可用的 OAM_BIN 始终会在 stderr 上注明；只有在找到的其他 oam 二进制文件都不可用时，才会注明它们及原因——较旧版本因较新版本而落选时不会输出信息。oam：行为相同，但无法使用 oam 时会报错退出，而不是回退到 Node。node：始终使用 Node——在 npx 下于进程内运行；当客户端通过 oam run 启动命令时，则转交给 PATH 上的 Node。忽略大小写；任何其他值均按 auto 处理。
NPMJS_MCP_SANDBOX	（无）	1 会在新启动的 oam（0.18.0+）中通过 --permission 运行服务，仅授予 npm 注册表主机（以及 NPM_REGISTRY 的主机）和服务读取的变量；文件系统和子进程访问仍被禁止。即使当前已在 oam 上运行，也会强制新启动一个实例。在 auto 模式下，如果找不到可用的 oam，或找到的 oam 启动失败，服务会在无沙盒的情况下运行，并在 stderr 上说明；将其与 NPMJS_MCP_RUNTIME=oam 配合使用，可使此情况变为致命错误。在 NPMJS_MCP_RUNTIME=node 下会被忽略。
OAM_BIN	（无）	指定优先于自动发现使用的 oam 二进制文件路径，版本必须为 0.18.0 或更高。如果文件不存在、版本较旧或无法运行，启动器会在 stderr 上说明，然后继续自动发现。自动发现会依次检查已设置的 OAM_INSTALL_DIR、安装位置（Windows 上依次为 %LOCALAPPDATA%\oam\bin 和 ~/.oam/bin，其他系统为 ~/.oam/bin），然后检查 PATH；它会询问找到的每个 oam 的版本，并使用最新版本；版本相同时优先选择路径顺序靠前的项。在 Windows 上只有 oam.exe 符合要求；绝不会运行 oam.cmd／oam.bat 垫片，且找不到可用 oam 时会在 stderr 上注明。在 NPMJS_MCP_RUNTIME=node 下，以及在没有沙盒且当前已运行于 oam 0.18.0+ 上时，均会忽略此变量。

运行时

此服务附带一个启动器，优先使用 oam 运行时，并在不可用时回退到 Node。服务本身是一个预先打包的 ESM 文件，只使用 node: 内置模块，因此 两条路径的行为完全一致——每条路径都已针对完整 MCP 接口（握手、全部 64 个工具、实时注册表调用）进行验证。

最低要求为最新版本 oam 0.18.0。 启动器会向找到的每个 oam 二进制文件查询版本，并运行其中不低于该版本的最新版本；绝不会使用更旧的 oam 提供服务。若找不到可用版本，则回退到 Node（设置 NPMJS_MCP_RUNTIME=oam 会将其变为硬错误）。详情请参阅配置。

回退不会产生额外开销：npm 已经启动 Node 来运行启动器，因此回退只需在进程内执行 import()——无需额外启动子进程，也不会增加启动时间。

oam 更快，但启动器并不快。 在 windows-arm64 上测得，n=12 中位数，从启动进程到收到第一个 MCP initialize 响应：

调用方式	耗时	相较于 node
oam run dist/index.js	116 ms	0.67x
node dist/index.js	172 ms	1.00x
此启动器（node 启动 oam）	243 ms	1.41x

npm 的 bin 入口是 Node 脚本，因此通过它调用 oam，既要付出 Node 的启动开销，又要付出 oam 的启动开销——总开销超过 oam 节省的时间。设置启动器是为了让 npx 用户自动使用 oam；它并非快速路径。

如果想获得 oam 的速度，请让 MCP 宿主直接调用它，跳过启动器：

{ "mcpServers": { "npmjs": { "command": "oam", "args": ["run", "/abs/path/to/dist/index.js"] } } }

基准测试说明：请使用已安装的 oam（~/.oam/bin），不要使用 cargo target/ 目录中的版本——并发的 cargo build 会在运行过程中替换二进制文件，而且新构建的字节尚未预热，而用于对比的 node.exe 已经预热。oam 仍处于预 Alpha 阶段；请在自己的硬件上重新测量。

oam 的 --permission 沙箱默认不启用。 设置 NPMJS_MCP_SANDBOX=1 后，启动器会在 oam（0.18.0 或更新版本）上启动服务，并授予以下权限：

• 授予对 registry.npmjs.org:443、api.npmjs.org:443 和 replicate.npmjs.com:443 的网络访问权限；若设置了 NPM_REGISTRY，还会授予对其主机和端口的访问权限（使用其自身端口，或 https / http 对应的 443 / 80 端口）。oam 会严格按 host:port 比较每个请求，因此每项授权都仅限于服务使用的那个端口；
• 环境变量访问权限仅授予服务实际读取的变量：NPM_TOKEN、NPM_REGISTRY、NPM_REQUEST_TIMEOUT_MS、NPM_RETRY_BACKOFF_MS 和 DEBUG；
• 文件系统和子进程访问权限一律拒绝。服务运行时不会读取任何文件，也不会启动任何进程，因此如果某个依赖突然尝试执行这些操作，运行时会将其阻止，而不是予以信任——对于持有 NPM_TOKEN 的进程而言，这一点尤为重要。

在默认设置 NPMJS_MCP_RUNTIME=auto 下，如果找不到可用的 oam，或者选中的 oam 无法启动，服务会在不使用沙箱的情况下运行，并在 stderr 上说明原因。还可设置 NPMJS_MCP_RUNTIME=oam，将此情况变为错误。

之所以不默认启用，是因为授权不完整时会静默失败，而不会明确报错。在 oam 0.9.0 上仅授权 registry.npmjs.org 的测试中，npm_health 仍返回 HTTP 200，但 weeklyDownloads: null 且没有错误：下载量来自 api.npmjs.org。缺少变量的后果更严重。oam 会从 process.env 中移除未授权的变量，而不是抛出异常，因此被拒绝访问的 NPM_TOKEN 看起来就像根本没有令牌，表现为“未认证”，而不是“被拒绝”。

其他 MCP 客户端：

客户端	配置文件
Claude Code	.mcp.json（项目根目录）或 ~/.claude.json（全局）
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code	.vscode/mcp.json

以上任一客户端都可以使用上面展示的同一 JSON 代码块。

工具（64）

搜索（1）

• npm_search — 使用限定条件（关键词、作者、作用域）搜索 npm 注册表。

软件包（6 项）

• npm_package — 元数据：描述、dist-tags、维护者、许可证、代码仓库。
• npm_version — 特定版本的详细元数据。
• npm_versions — 所有已发布版本及其日期。
• npm_readme — README 内容。
• npm_dist_tags — Dist-tags（latest、next、beta 等）。
• npm_types — TypeScript 类型支持（内置类型或 @types/*）。

依赖（3 项）

• npm_dependencies — 依赖列表（生产、开发、peer、可选）。
• npm_dep_tree — 传递依赖树（深度可配置）。
• npm_license_check — 软件包及其直接依赖的许可证审查。

下载量（4 项）

• npm_downloads — 指定时间段的总下载量。
• npm_downloads_range — 每日下载量明细。
• npm_downloads_bulk — 比较最多 128 个软件包的下载量。
• npm_version_downloads — 各版本的下载量。

安全（3 项）

• npm_audit — 检查软件包是否存在已知漏洞。
• npm_audit_deep — 完整审查，包含 CVSS 评分、CWE 和修复建议。
• npm_signing_keys — Registry 的 ECDSA 签名密钥。

分析（4 项）

• npm_compare — 并排比较 2–5 个软件包。
• npm_health — 维护情况、下载量、安全性和弃用情况摘要。
• npm_maintainers — 维护者和发布历史。
• npm_release_frequency — 发布节奏和间隔。

Registry（3 项）

• npm_registry_stats — npm 全站总下载量。
• npm_recent_changes — CouchDB changes feed 中最近的发布记录。
• npm_ops_playbook — npm 操作的规范方案。不确定该使用哪个工具时，请先调用此工具。

来源与信任（2 项）

• npm_provenance — Sigstore 证明（SLSA、发布）。
• npm_trusted_publishers — 与 CI/CD 提供商之间的 OIDC 信任关系。

身份验证（5 项，需要 NPM_TOKEN）

• npm_whoami — 已通过身份验证的用户。
• npm_profile — 个人资料、电子邮件、2FA 状态。
• npm_tokens — 列出访问令牌。
• npm_verify_token — 单次调用的能力检查。调试写入失败时，请先调用此工具。
• npm_user_packages — 用户发布的软件包。

访问与组织（7 项，需要 NPM_TOKEN）

• npm_collaborators — 软件包协作者及权限。
• npm_package_access — 软件包访问设置。
• npm_org_members — 组织成员及角色。
• npm_org_packages — 组织软件包。
• npm_org_teams — 组织团队。
• npm_team_packages — 团队软件包权限。
• npm_team_members — 团队成员及角色。

工作流（2 项）

• npm_check_auth — 身份验证健康检查，并检查是否能以无头方式发布。
• npm_publish_preflight — 发布前验证清单。

写入操作（19 项，需要具有写入权限范围的 NPM_TOKEN）

这些操作绕过了 CLI/2FA 带来的阻碍，因此可避免 npm deprecate 等命令在本地失败。所有操作都使用你的 NPM_TOKEN 调用 HTTP API。

• npm_deprecate — 弃用软件包或特定版本（强制遵守 registry 的 1024 字符消息上限；消息标点不受限制）。
• npm_undeprecate — 清除弃用状态。
• npm_unpublish_version — 取消发布某个版本。需要 confirm: true。
• npm_unpublish_package — 取消发布整个软件包。需要 confirm: true。
• npm_dist_tag_set — 将 dist-tag 指向某个版本。
• npm_dist_tag_remove — 移除 dist-tag（拒绝移除 latest）。
• npm_owner_add — 添加维护者（通过 /-/user/ 解析用户）。
• npm_owner_remove — 移除维护者（防止自己被锁在外面）。
• npm_access_set — 设置公开、私有或受限访问权限。
• npm_access_set_mfa — 配置 2FA 要求（none/publish/automation）。
• npm_team_grant / npm_team_revoke — 授予/撤销团队对软件包的权限。
• npm_team_create / npm_team_delete — 在组织中创建/删除团队。
• npm_team_member_add / npm_team_member_remove — 管理团队成员。
• npm_org_member_set / npm_org_member_remove — 管理组织成员身份和角色。
• npm_token_revoke — 根据密钥撤销访问令牌。

Webhook（5 个，需要 NPM_TOKEN）

• npm_hook_add — 在软件包、范围或用户上注册 Webhook。
• npm_hook_list — 列出 Webhook（可选软件包筛选条件）。
• npm_hook_get — 获取单个 Webhook。
• npm_hook_update — 更新端点／密钥。
• npm_hook_remove — 删除 Webhook。

操作决策矩阵

操作	首选路径	原因
读取（搜索／查看／统计）	使用这些 MCP 工具，无需身份验证	快速、零阻碍
弃用／dist-tag／取消发布	npm_deprecate、npm_dist_tag_* 等	HTTP API，使用可绕过 2FA 的令牌时无需经历 CLI 的 2FA 阻碍
所有者／访问权限／团队／组织／令牌变更	npm_owner_*、npm_access_set*、npm_team_*、npm_org_member_*、npm_token_revoke	自 2026-07-31 起，这些操作需要交互式 2FA 挑战；出现 401/403 时，错误会指出由人工运行的 npm 命令
发布	在工作站上运行 bash release.sh X.Y.Z	此仓库没有 CI 发布工作流（已在 b2c256c 中移除）。注意：工作站发布不会附带 sigstore 来源证明——--provenance 需要 CI OIDC。
取消发布	npm_unpublish_version（使用 confirm: true）	比 CLI 更安全；72 小时内不可撤销
CLI 后备方案	由能够响应一次性密码提示的人工运行错误中指出的 npm 命令	对需要交互式 2FA 的变更出现 401/403 时，或出现消息中指出该命令的 422 时

在任何会话开始时调用 npm_ops_playbook，以获取最新的矩阵。

示例

审核依赖项

> "What vulnerabilities does lodash 4.17.20 have and what's the fix?"
→ npm_audit_deep({
    name: "my-project",              // the PROJECT being audited, not the dependency
    version: "1.0.0",
    dependencies: { lodash: "4.17.20" }   // required — the set to audit
  })

若要快速一次检查多个软件包，npm_audit 可直接接收名称到版本的映射：npm_audit({ packages: { lodash: ["4.17.20"] } })。

弃用软件包

> "Deprecate @myorg/legacy-sdk with a pointer to @myorg/sdk"
→ npm_deprecate({ name: "@myorg/legacy-sdk", message: "Renamed to @myorg/sdk — install that instead" })

比较软件包健康状况

> "Compare fastify vs express vs koa for maintenance health"
→ npm_compare({ packages: ["fastify", "express", "koa"] })
→ npm_health({ name: "fastify" }) // ...etc

轮换 dist-tag

> "Point @myorg/pkg@latest at 3.2.1"
→ npm_dist_tag_set({ name: "@myorg/pkg", tag: "latest", version: "3.2.1" })

排查写入失败

> "My deprecate keeps returning 401 — what's wrong?"
→ npm_verify_token()  // Confirms token scope, packages, 2FA state
→ npm_ops_playbook()  // Returns the canonical retry sequence

故障排除

“Error: NPM_TOKEN is required”

• 你调用的工具需要身份验证。将 NPM_TOKEN 添加到 MCP 配置的 env 区块中，然后重启客户端。
• 建议使用细粒度访问令牌，仅授予你要操作的软件包和组织的权限。

“HTTP 401 Unauthorized”或“HTTP 403 Forbidden”

• 你的令牌缺少目标软件包的权限。调用 npm_verify_token，查看该令牌实际可以写入哪些软件包和组织。
• OTP 挑战会以 401 返回，2FA 策略拒绝会以 403 返回；两者都不会是 422。对于弃用、取消弃用、dist-tag 和取消发布，启用了 2FA 绕过功能的细粒度访问令牌可解决这两种情况。经典令牌（包括 Automation 令牌）已于 2025 年 12 月撤销。
• 自 2026-07-31 起，所有者、访问权限、团队成员资格和授权、组织成员资格及令牌变更都需要交互式 2FA 挑战，即使使用启用了 2FA 绕过功能的令牌也一样。没有任何令牌能解决此问题：错误会指出供人工运行并响应一次性密码提示的确切 npm 命令。

写入时出现“HTTP 422 Unprocessable”

• 首先阅读末尾的 Raw: 正文；它是注册表给出的实际原因。在此之前，消息会说明该调用发送了什么，以及可能违反了哪些已记录的 npm 规则；之后（如果有）会提供等效的 npm CLI 命令，该命令会打印注册表的完整错误，并在需要时提示输入一次性密码。
• 对于 npm_deprecate，如果 versionRange 未匹配任何已发布版本，或消息超过 1024 个字符，都会在写入前于本地被拒绝并返回 HTTP 400，因此两者都不会导致 422。范围错误会列出已发布的版本；请根据该列表或使用 npm_versions 修正范围。
• 消息中的标点不是原因。将末尾句号换成破折号并不能消除 422。

Windows：MCP 服务无法启动

• 使用快速入门部分中的 cmd /c npx ... 模式。Node 20+ 无法直接启动 .cmd 文件。

要求

• Node.js 20.11+（package.json 声明了 engines.node: ">=20.11.0"）
• （可选）用于写入操作的 npm 访问令牌

贡献

git clone https://github.com/YawLabs/npmjs-mcp.git
cd npmjs-mcp
npm install
npm run lint       # Biome check
npm run lint:fix   # Auto-fix
npm run build      # tsc + esbuild bundle
npm test           # node --test

完整工作流（包括发布流程）请参阅 CONTRIBUTING.md。

许可证

MIT