npm

英语 | 한국어 | 中文 | 日本語

npm-mcp

让 AI 助手管理 npm 包的 MCP 服务。通过 Claude Code 或任何 MCP 客户端，即可发布、管理版本、搜索、审计、安装等。

此 MCP 服务需要 Node.js 20 或更高版本。下文注明的部分 npm CLI 功能可能需要更新的 Node.js/npm 组合。

适用场景

任务	工具
“将此包发布到 npm”	publish
“检查是否有过时的依赖项”	outdated
“对我的包运行安全审计”	audit
“在 npm 上搜索身份验证库”	search
“升级版本并发布”	先运行 version，再运行 publish
“检查谁拥有这个 npm 包”	owner
“查看我的包的下载统计信息”	view

面向 AI Agent： 查看 llms.txt 了解机器可读的摘要。将 templates/CLAUDE.md 或 templates/AGENTS.md 复制到项目中，让 Agent 了解此 MCP。

为什么要用

你正在 Claude Code 中构建一个库。代码写完后，你需要发布它。无需切换到终端：

You: publish this package to npm with public access
Claude: [calls publish tool] Published @yourorg/[email protected] successfully

就这么简单。无需切换上下文。

设置

1. 安装

git clone https://github.com/mikusnuz/npm-mcp.git
cd npm-mcp
npm install
npm run build

2. 获取 npm 令牌

前往 npmjs.com > Account > Access Tokens，创建一个可访问所需包的 细粒度访问令牌。经典令牌和自动化令牌已不再受支持。仅用于暂存的令牌可用于下文的 stage 工作流。已有的 npm login 凭据也可使用。

3. 添加到 Claude Code

编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "npm-mcp": {
      "command": "node",
      "args": ["/path/to/npm-mcp/dist/index.js"],
      "env": {
        "NPM_TOKEN": "npm_xxxxxxxxxxxx"
      }
    }
  }
}

或者，如果你已在本地运行过 npm login，则可以省略 NPM_TOKEN——它会自动使用你的 ~/.npmrc。

工具

发布与版本管理

工具	描述
publish	将包发布到 npm 注册表
stage	暂存、列出、检查、下载、批准或拒绝待处理的包版本
version	升级包版本（patch/minor/major/pre*）
unpublish	移除包版本
deprecate	将某个版本标记为弃用（或使用空消息取消弃用）
pack	预览即将发布的内容

包信息

工具	描述
view	查看注册表中的包信息
search	搜索 npm 注册表
bugs	获取包的问题跟踪网址
repo	获取包的仓库网址
docs	获取包的文档网址
diff	显示包版本之间的差异

依赖项管理

工具	描述
install	安装包
pending-scripts	列出未经审核的依赖项安装脚本，不更改策略（npm 12+）
approve-scripts	批准已审核并指定名称的依赖项，同时固定版本（npm 12+）
deny-scripts	禁止指定依赖项的安装脚本，适用于所有版本（npm 12+）
uninstall	移除包
update	将包更新到符合语义化版本规则的最新版本
outdated	检查过时的包
ls	列出已安装的包
explain	说明安装某个包的原因
dedupe	减少依赖树中的重复项
prune	移除多余的包
fund	显示依赖项的资助信息
query	使用类似 CSS 选择器的语法查询包

安全与诊断

npm 12 会阻止未经批准的依赖安装脚本。使用绝对项目 path 调用 pending-scripts，审核软件包，然后将明确的软件包名称传递给 approve-scripts 或 deny-scripts。这些命令只会更新策略，不会运行脚本；请另行重新运行预期的安装或构建操作。没有批量批准选项。如果有可信的解析版本可用，npm 会在批准中固定该版本；如果较旧的锁定文件导致只能按名称批准，请检查相关警告。仅对于全局安装，install.allowScripts 可接受明确列出的已审核名称。较旧的 npm 版本不支持这些选项；请使用 NPM_PATH 选择 npm 12 或更高版本。请参阅 npm 脚本批准。

工具	描述
audit	运行安全审计（可选自动修复）
sbom	生成软件物料清单（CycloneDX/SPDX）
doctor	检查 npm 环境健康状况
ping	检查注册表连通性

配置与身份验证

工具	描述
whoami	检查当前已验证用户
token	管理访问令牌（列出/撤销）
access	设置或查看软件包的访问级别
owner	管理软件包所有者（ls/add/rm）
dist-tag	管理发行标签（ls/add/rm）
profile	查看或修改 npm 配置文件设置
config	查看 npm 配置（只读）

项目设置

工具	描述
init	初始化新的 package.json
pkg	以编程方式管理 package.json 字段
ci	根据锁定文件执行干净安装（用于 CI）
run-script	运行 package.json 中定义的脚本
link	为本地软件包创建符号链接以用于开发
cache	管理 npm 缓存

示例

发布带作用域的软件包：

publish({ path: "/home/user/my-lib", access: "public" })

升级版本并发布：

version({ path: "/home/user/my-lib", bump: "patch" })
publish({ path: "/home/user/my-lib" })

发布前检查软件包内容：

pack({ path: "/home/user/my-lib", dryRun: true })

搜索现有软件包：

search({ query: "react state management", limit: 5 })

查看软件包详情：

view({ package: "@yourorg/lib", field: "versions" })

安装软件包：

install({ path: "/home/user/my-app", packages: ["express", "cors"], saveDev: false })

检查过时的依赖项：

outdated({ path: "/home/user/my-app" })

比较版本：

diff({ specs: ["[email protected]", "[email protected]"] })

生成 SBOM：

sbom({ path: "/home/user/my-app", format: "spdx", production: true })

查询依赖项：

query({ path: "/home/user/my-app", selector: ":root > .prod" })

身份验证

分阶段发布

分阶段发布要求 npm CLI 11.15.0 或更高版本，且 Node.js 22.14.0 或更高版本。请检查 npm stage --help；NPM_PATH 可用于选择单独的 npm 安装。请参阅分阶段发布的先决条件。

stage({ action: "publish", path: "/home/user/my-lib", access: "public" })
stage({ action: "list", package: "@yourorg/lib" })
stage({ action: "view", stageId: "returned-stage-id" })
stage({ action: "download", stageId: "returned-stage-id", path: "/home/user/review" })
stage({ action: "approve", stageId: "returned-stage-id", otp: "123456" })
// Or reject the staged version:
stage({ action: "reject", stageId: "returned-stage-id", otp: "123456" })

暂存不会发布软件包；批准操作才会发布。批准和拒绝均需要维护者 2FA。dryRun 仅适用于 action: "publish" 的 stage。使用仅限暂存的令牌直接发布会返回 E_STAGE_REQUIRED。npm 计划于 2027 年 1 月移除使用细粒度令牌直接发布的功能。 请参阅 npm 暂存和 令牌要求。

pkg 可直接接受 JSON 值：value: "my-package"、value: true、 value: ["keyword"] 或 value: { test: "node --test" }。字符串会保持为字符串； 传递数组或对象之前，请勿将其转换为字符串。

方式	方法
NPM_TOKEN（推荐）	在 MCP 配置中设置 NPM_TOKEN 环境变量。从 npmjs.com > Access Tokens 获取令牌
npm login	先在终端运行 npm login。自动使用保存在 ~/.npmrc 中的令牌

当 npm 要求 2FA 时，请传递 otp，包括分阶段批准/拒绝以及软件包维护者或令牌变更操作。自 2026 年 8 月起，绕过 2FA 的令牌无法在账户或治理操作中绕过第二重验证。令牌会过期；需要时请续期已配置的令牌，或使用 npm login 刷新本地凭据。

环境变量

变量	默认值	描述
NPM_TOKEN	--	npm 身份验证令牌
NPM_PATH	npm	npm 二进制文件的路径（如果不在 PATH 中）

许可证

MIT