@yawlabs/npmjs-mcp

Run npm registry operations from Claude Code, Cursor, and any MCP client. 64 tools covering the full registry surface: package intelligence, security audits, dependency analysis, org/team management, and the write ops that normally fight you locally (npm deprecate, npm dist-tag, npm owner, npm unpublish).

Built and maintained by Yaw Labs.

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

Why this one?

Other npm MCP servers wrap npm search and call it done. This one doesn't.

• Full registry HTTP surface — 64 tools across reads, writes, orgs, teams, hooks, provenance, trusted publishers, and ops health. Not just npm view.

• Write ops that actually work in agents — npm_deprecate, npm_dist_tag_set, npm_owner_add, npm_unpublish_version go directly to the HTTP API with your token. No 2FA prompts, no --otp hunts, no ENEEDAUTH from a session-bound .npmrc.

• Agent-aware failure surfacing — write tools detect non-interactive context and return specific human-runnable commands (npm login --auth-type=web) instead of looping on unrecoverable errors.

• Safety by default — npm_unpublish_* requires confirm: true. npm_owner_remove blocks you from locking yourself out. npm_deprecate validates the message format (em-dash, no trailing period) that npmjs.com's API actually accepts.

• Ops playbook built in — npm_ops_playbook returns the canonical tool-vs-CLI-vs-CI decision matrix so your agent picks the right path on the first try.

• Tool annotations — every tool declares readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so MCP clients can skip confirmation on safe ops.

• No API key required for reads — search, packages, downloads, security, dep tree, licenses all work anonymously. Auth is opt-in via NPM_TOKEN.

• Instant startup — ships as a single bundled file with zero runtime dependencies. No 5-minute node_modules install.

• Input hardening — package names, scopes, versions, dist-tags, and team names are all regex-validated against npm's actual constraints. Defends against CRLF and path-traversal in URL construction.

Related MCP server: mcp-npm-tools

Quick start

1. Create .mcp.json in your project root

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

Why the extra step on Windows? Since Node 20, child_process.spawn cannot directly execute .cmd files (that's what npx is on Windows). Wrapping with cmd /c is the standard workaround.

2. Restart and approve

Restart Claude Code (or your MCP client) and approve the npm MCP server when prompted.

3. (Optional) Add your npm token for write operations

Read-only tools work without any setup. For write tools (deprecate, dist-tag, owner, team_*, org_member_*, unpublish, hook_*, access_set*, token_revoke), add NPM_TOKEN to the env block:

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

Use a Granular Access Token scoped to just the packages and orgs you want your agent to manage.

That's it. Now ask your AI assistant:

"Deprecate my-old-pkg 1.x with a pointer to v2"

"What's the dep tree for fastify look like three levels deep?"

"Audit express for known CVEs and tell me the fix"

"Who are the maintainers of next.js and when did each one last publish?"

Configuration

Runtime

The server ships a launcher that prefers the oam runtime and falls back to Node. The server itself is a pre-bundled ESM file using only node: builtins, so both paths behave identically — verified against the full MCP surface (handshake, all 64 tools, live registry calls) on each.

Falling back costs nothing: npm has already started Node to run the launcher, so the fallback is an in-process import() — no extra spawn, no extra startup.

oam is faster, but the launcher is not. Measured on windows-arm64, n=12 medians, spawn to first MCP initialize response:

npm bin entries are Node scripts, so reaching oam through one costs Node's startup plus oam's — more than oam saves. The launcher exists so npx users get oam automatically; it is not the fast path.

If you want oam's speed, point your MCP host straight at it and skip the launcher:

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

Benchmarking note: measure an installed oam (~/.oam/bin), never one out of a cargo target/ directory — a concurrent cargo build replaces the binary mid-run, and fresh bytes are cold where the node.exe you are comparing against is warm. oam is pre-alpha; re-measure on your own hardware.

oam's --permission sandbox is deliberately not used: it denies network access and implements no grant to restore it, which would leave every registry call failing.

Alternate MCP clients:

Use the same JSON block shown above in any of these.

Tools (64)

Search (1)

• npm_search — Search the npm registry with qualifiers (keywords, author, scope).

Packages (6)

• npm_package — Metadata: description, dist-tags, maintainers, license, repository.

• npm_version — Detailed metadata for a specific version.

• npm_versions — All published versions with dates.

• npm_readme — README content.

• npm_dist_tags — Dist-tags (latest, next, beta, etc).

• npm_types — TypeScript type support (built-in types or @types/*).

Dependencies (3)

• npm_dependencies — Dependency lists (prod, dev, peer, optional).

• npm_dep_tree — Transitive dependency tree (configurable depth).

• npm_license_check — License audit of a package and its direct deps.

Downloads (4)

• npm_downloads — Total download count for a period.

• npm_downloads_range — Daily download breakdown.

• npm_downloads_bulk — Compare downloads for up to 128 packages.

• npm_version_downloads — Per-version download counts.

Security (3)

• npm_audit — Check packages for known vulnerabilities.

• npm_audit_deep — Full audit with CVSS scores, CWEs, fix recommendations.

• npm_signing_keys — Registry ECDSA signing keys.

Analysis (4)

• npm_compare — Compare 2–5 packages side-by-side.

• npm_health — Maintenance, downloads, security, deprecation summary.

• npm_maintainers — Maintainers and publish history.

• npm_release_frequency — Release cadence and gaps.

Registry (3)

• npm_registry_stats — Total npm-wide download counts.

• npm_recent_changes — Recent publishes from the CouchDB changes feed.

• npm_ops_playbook — Canonical recipes for npm operations. Call this first when unsure which tool to use.

Provenance & trust (2)

• npm_provenance — Sigstore attestations (SLSA, publish).

• npm_trusted_publishers — OIDC trust relationships with CI/CD providers.

Auth (5, requires NPM_TOKEN)

• npm_whoami — Authenticated user.

• npm_profile — Profile, email, 2FA status.

• npm_tokens — List access tokens.

• npm_verify_token — One-call capability check. Call this first when debugging write failures.

• npm_user_packages — Packages published by a user.

Access & orgs (7, requires NPM_TOKEN)

• npm_collaborators — Package collaborators and permissions.

• npm_package_access — Package access settings.

• npm_org_members — Org members and roles.

• npm_org_packages — Org packages.

• npm_org_teams — Org teams.

• npm_team_packages — Team package permissions.

• npm_team_members — Team members and roles.

Workflows (2)

• npm_check_auth — Auth health check with headless publish feasibility.

• npm_publish_preflight — Pre-publish validation checklist.

Write operations (19, requires NPM_TOKEN with write scope)

These bypass the CLI/2FA friction that makes npm deprecate and friends fail locally. All use the HTTP API with your NPM_TOKEN.

• npm_deprecate — Deprecate a package or specific versions (enforces the registry's 1024-char message limit; message punctuation is not constrained).

• npm_undeprecate — Clear deprecation.

• npm_unpublish_version — Unpublish a version. Requires confirm: true.

• npm_unpublish_package — Unpublish an entire package. Requires confirm: true.

• npm_dist_tag_set — Point a dist-tag at a version.

• npm_dist_tag_remove — Remove a dist-tag (refuses latest).

• npm_owner_add — Add a maintainer (resolves user via /-/user/).

• npm_owner_remove — Remove a maintainer (prevents self-lockout).

• npm_access_set — Set public/private/restricted access.

• npm_access_set_mfa — Configure 2FA requirement (none/publish/automation).

• npm_team_grant / npm_team_revoke — Grant/revoke team permissions on a package.

• npm_team_create / npm_team_delete — Create/delete a team in an org.

• npm_team_member_add / npm_team_member_remove — Manage team members.

• npm_org_member_set / npm_org_member_remove — Manage org membership and roles.

• npm_token_revoke — Revoke an access token by key.

Webhooks (5, requires NPM_TOKEN)

• npm_hook_add — Register a webhook on a package, scope, or user.

• npm_hook_list — List webhooks (optional package filter).

• npm_hook_get — Fetch a single webhook.

• npm_hook_update — Update endpoint/secret.

• npm_hook_remove — Delete a webhook.

Operation decision matrix

Call npm_ops_playbook at the start of any session to get the up-to-date matrix.

Examples

Audit a dependency

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

For a quick check across several packages at once, npm_audit takes the name-to-versions map directly: npm_audit({ packages: { lodash: ["4.17.20"] } }).

Deprecate a package

> "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 package health

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

Rotate a dist-tag

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

Debug a write failure

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

Troubleshooting

"Error: NPM_TOKEN is required"

• The tool you called needs auth. Add NPM_TOKEN to the env block of your MCP config and restart the client.

• Prefer a Granular Access Token scoped to just the packages and orgs you want touched.

"HTTP 401 Unauthorized" or "HTTP 403 Forbidden"

• Your token lacks scope on the target package. Call npm_verify_token — it reports which packages and orgs the token can actually write.

• If the package requires 2FA for writes, your token must be an automation token or come from an OIDC trusted publisher. A user token will 403.

"HTTP 422 Unprocessable" on deprecate

• Common cause: message format. Use an em-dash and no trailing period: "Renamed to @x/y — install that instead", not "Renamed to @x/y. Install that instead."

• Another: specifying a versions range that doesn't match any published version. Call npm_versions to confirm.

Windows: MCP server doesn't start

• Use the cmd /c npx ... pattern from the Quick start section. Node 20+ can't spawn .cmd files directly.

Requirements

• Node.js 20+ (the CI matrix tests 20 and 22; package.json declares engines.node: ">=20")

• (Optional) npm access token for write operations

Contributing

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

See CONTRIBUTING.md for the full workflow, including release process.

License

MIT