Npm MCP

What mikusnuz/npm-mcp does

mikusnuz/npm-mcp brings npm workflows into MCP-compatible AI clients. It can work with local project directories for package installation, removal, updates, version changes, packing, auditing, and other dependency operations. It also queries the npm registry for package metadata, search results, documentation links, repository links, bug trackers, version differences, and download-related package information.

Publishing workflows include direct publication, version bumps, package removal, deprecation, and dry-run packing. The stage tool supports staged package publication, listing staged versions, inspecting or downloading them, and approving or rejecting a staged release. Approval and rejection require maintainer two-factor authentication.

How it works

The server runs as a Node.js process and exposes npm operations as MCP tools. Local-project tools accept a project path; registry and package tools accept package names or version specifications. For example, an agent can bump a project from its current version, publish it, inspect the contents that would be packed, or compare two package versions.

Authentication can come from an NPM_TOKEN supplied in the MCP client configuration or from credentials already stored by npm login in the user’s npm configuration. Two-factor authentication codes can be passed for operations that require them, including staged release approval or rejection and certain maintainer or token changes.

Dependency script controls are designed for npm 12 and later. An agent can list unreviewed install scripts, then approve specific reviewed dependencies with version pinning or deny named dependencies. These policy operations do not execute the scripts; the intended installation or build must be run separately.

Setup and configuration

Install the project from its repository, install dependencies, and build it with npm:

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

Configure an MCP client to launch dist/index.js with Node.js. A typical configuration supplies the npm token through NPM_TOKEN:

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

Use NPM_PATH when the npm executable is not the one available on the system path, or when a separate npm installation is needed. Staged publishing requires npm 11.15.0 or later and Node.js 22.14.0 or later. The server requires Node.js 20 or newer overall.

Tools and capabilities

Publishing and release management include publish, stage, version, unpublish, deprecate, and pack. Registry inspection includes view, search, bugs, repo, docs, and diff.

Project dependency operations include install, uninstall, update, outdated, ls, explain, dedupe, prune, fund, and query. Security and diagnostics include audit, sbom, doctor, and ping. The server also exposes pending-scripts, approve-scripts, and deny-scripts for npm 12 script policy workflows, plus whoami for checking the authenticated npm account.

The package supports common release tasks such as publishing a scoped package, checking outdated dependencies, generating CycloneDX or SPDX SBOM output, and querying dependencies with CSS-like selectors.

Limitations and notes

Staged publication is separate from direct publication: the package is not published until a staged version is approved. Approval and rejection require maintainer 2FA, and staged workflows may require a stage-capable token. Direct publishing with a stage-only token fails with E_STAGE_REQUIRED.

npm version differences affect available operations. In particular, the install-script approval tools require npm 12 or newer, and older npm versions do not support those options. Approval is explicit rather than bulk, and a lockfile can result in a name-only approval when a trusted resolved version cannot be pinned.