io.github.mikusnuz/npm

English | 한국어 | 中文 | 日本語

npm-mcp

MCP server that lets AI assistants manage npm packages. Publish, version, search, audit, install, and more -- all through Claude Code or any MCP client.

The MCP server requires Node.js 20 or newer. Individual npm CLI features may require a newer Node.js/npm combination as noted below.

When to Use

For AI agents: See llms.txt for a machine-readable summary. Copy templates/CLAUDE.md or templates/AGENTS.md into your project to teach your agent about this MCP.

Why

You're in Claude Code building a library. You finish the code, and now you need to publish it. Instead of switching to a terminal:

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

That's it. No context switching.

Setup

1. Install

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

2. Get npm token

Go to npmjs.com > Account > Access Tokens and create a granular access token with access to the packages you need. Classic and Automation tokens are no longer supported. A stage-only token uses the stage workflow below. Existing npm login credentials also work.

3. Add to Claude Code

Edit ~/.claude/settings.json:

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

Or if you've already run npm login locally, skip NPM_TOKEN -- it uses your ~/.npmrc automatically.

Tools

Publishing & Versioning

Package Info

Dependency Management

Security & Diagnostics

npm 12 blocks unapproved dependency install scripts. Call pending-scripts with an absolute project path, review the packages, then pass explicit package names to approve-scripts or deny-scripts. These commands update policy without running scripts; rerun the intended install/build separately. There is no bulk approval option. npm pins approvals when a trusted resolved version is available; check its warnings if an older lockfile forces a name-only approval. For global installs only, install.allowScripts accepts an explicit list of reviewed names. Older npm versions do not support these options; select npm 12+ using NPM_PATH. See npm script approval.

Configuration & Auth

Project Setup

Examples

Publish a scoped package:

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

Bump version and publish:

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

Check what's inside before publishing:

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

Search for existing packages:

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

View package details:

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

Install packages:

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

Check outdated dependencies:

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

Compare versions:

diff({ specs: ["lodash@4.17.20", "lodash@4.17.21"] })

Generate SBOM:

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

Query dependencies:

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

Auth

Staged publishing

Staged publishing requires npm CLI 11.15.0 or later and Node.js 22.14.0 or later. Check npm stage --help; NPM_PATH can select a separate npm installation. See the staged publishing prerequisites.

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

Staging does not publish the package; approval does. Approval and rejection require maintainer 2FA. dryRun applies only to stage with action: "publish". A direct publish with a stage-only token returns E_STAGE_REQUIRED. npm plans to remove direct publishing with granular tokens in January 2027. See npm staging and token requirements.

pkg accepts JSON values directly: value: "my-package", value: true, value: ["keyword"], or value: { test: "node --test" }. Strings stay strings; do not stringify arrays or objects before passing them.

Pass otp when npm requires 2FA, including staged approval/rejection and package maintainer or token changes. Since August 2026, bypass-2FA tokens cannot bypass the second factor for account or governance operations. Tokens expire; renew the configured token when needed or refresh local credentials with npm login.

Environment Variables

License

MIT