@yawlabs/npmjs-mcp
One-line summary: An npm registry MCP server giving AI agents 64 tools for package intel, security audits, dependency analysis, org/team management, webhooks, and guarded write operations (deprecate, dist-tag, owner, unpublish) — reads work anonymously, writes need NPM_TOKEN.
Search & package data —
npm_searchwith qualifiers (keywords:,author:,scope:,not:insecure), plusnpm_package,npm_version,npm_versions,npm_readme,npm_dist_tags,npm_types.Dependencies & licenses —
npm_dependencies(prod/dev/peer/optional),npm_dep_tree(transitive, depth up to 5, 60s cap),npm_license_check(flags missing/non-SPDX-verbatim licenses).Downloads & registry stats — total, daily breakdown, per-version, bulk compare (up to 128 unscoped packages), registry-wide stats, and recent publishes via the CouchDB changes feed.
Security —
npm_audit(bulk advisory),npm_audit_deep(CVSS, CWEs, fix recommendations),npm_signing_keys.Analysis —
npm_compare(2–5 packages),npm_health,npm_maintainers+ publish history,npm_release_frequency.Provenance & trust — Sigstore attestations (
npm_provenance, retrieval only, no verification) and OIDC trusted publishers.Auth diagnostics —
npm_whoami,npm_profile,npm_tokens,npm_verify_token,npm_user_packages,npm_check_auth,npm_publish_preflight(all return human-runnable commands instead of impossible agent retries).Read-only org/access audits — org members/packages/teams, team packages/members, package collaborators, package access/MFA settings.
Write ops (need token with write scope) —
npm_deprecate/npm_undeprecate,npm_dist_tag_set/remove,npm_owner_add/remove(self-lockout blocked),npm_access_set,npm_access_set_mfa,npm_unpublish_version/package(requireconfirm: true).Team & org administration — team create/delete, grant/revoke package permissions, add/remove team members, set/remove org members (preserves existing role when omitted),
npm_token_revoke.Webhooks — add/list/get/update/remove; secrets are redacted from responses and
updatealways rotates them.Operational guidance —
npm_ops_playbookreturns the canonical tool-vs-CLI-vs-CI decision matrix; all tools carryreadOnlyHint/destructiveHint/idempotentHint/openWorldHintannotations so clients can skip confirmation on safe calls.
Provides tools for interacting with the npm registry, including package search, metadata retrieval, dependency analysis, security audits, download statistics, package comparison, provenance, and write operations such as deprecation, dist-tag management, owner management, unpublishing, and org/team administration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@yawlabs/npmjs-mcp What are the maintainers of lodash?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@yawlabs/npmjs-mcp
One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Tested with Yaw MCP 1.1.13 or newer. Or install manually below.
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.
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_undeprecate,npm_dist_tag_set,npm_unpublish_versiongo directly to the HTTP API with a Granular Access Token that has 2FA bypass. No 2FA prompts, no--otphunts, noENEEDAUTHfrom a session-bound.npmrc. (Since 2026-07-31 npm requires an interactive 2FA challenge for owner, access, team membership and grant, org membership and token changes even with 2FA bypass; for those tools the error names the exactnpmcommand a human runs.)Agent-aware failure surfacing —
npm_check_authandnpm_publish_preflightdetect a non-interactive context and hand back a human-runnable command, and every write error names what was sent and the npm CLI equivalent, instead of looping on unrecoverable errors.Safety by default —
npm_unpublish_*requiresconfirm: true.npm_owner_removeblocks you from locking yourself out.npm_deprecaterejects a message over the registry's 1024-character limit before sending it.Ops playbook built in —
npm_ops_playbookreturns 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, andopenWorldHint, 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_modulesinstall.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: Augments MCP Server
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.spawncannot directly execute.cmdfiles (that's whatnpxis on Windows). Wrapping withcmd /cis 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
Environment variable | Default | Description |
| (none) | npm access token. Required only for write/auth/org/access/hooks tools. Use a Granular Access Token (with 2FA bypass for headless writes); classic tokens, including Automation tokens, were revoked in December 2025. |
|
| Alternate registry (enterprise/private). Must support the npm HTTP API shape. |
|
| Timeout for each attempt of a registry request, in milliseconds, including reading the body. A read retries a timeout, a network error, or HTTP 429/502/503/504, up to 3 attempts in all, so a stalled read can take about three times this value. A write is never re-sent after a timeout or network error, because the registry may already have applied it; it retries only on 429/503. A value that is not a positive, finite number ( |
|
| Base wait before a retry, doubled each time: 500 ms, then 1000 ms by default. When the retried response carries a |
| (none) | Logs one line per attempt of every npm API call to stderr, prefixed |
|
|
|
| (none) |
|
| (none) | Path to an |
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.
oam 0.20.2, the latest release, is the minimum. The launcher asks every oam binary it can find for its version and runs the newest one at or above it, never serves on an older oam, and falls back to Node when there is none (NPMJS_MCP_RUNTIME=oam turns that into a hard error). See Configuration for the details.
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:
invocation | time | vs node |
| 116 ms | 0.67x |
| 172 ms | 1.00x |
this launcher (node spawns oam) | 243 ms | 1.41x |
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 opt-in. Set NPMJS_MCP_SANDBOX=1 and the launcher spawns the server on oam (0.20.2 or newer) with:
network granted to
registry.npmjs.org:443,api.npmjs.org:443andreplicate.npmjs.com:443, plus the host and port ofNPM_REGISTRYwhen it is set (its own port, or 443 / 80 forhttps/http). oam compares each request ashost:portexactly, so every grant is scoped to the one port the server uses;environment granted to exactly the variables the server reads:
NPM_TOKEN,NPM_REGISTRY,NPM_REQUEST_TIMEOUT_MS,NPM_RETRY_BACKOFF_MSandDEBUG;filesystem and subprocess access denied outright. The server reads no files at runtime and spawns nothing, so a dependency that suddenly wants either is stopped by the runtime instead of trusted — which matters for a process holding an
NPM_TOKEN.
Under the default NPMJS_MCP_RUNTIME=auto, if no usable oam is found, or the one chosen fails to start, the server runs without the sandbox and says so on stderr. Set NPMJS_MCP_RUNTIME=oam as well to make that an error.
It is not the default because an incomplete grant fails silently rather than loudly. Measured on oam 0.9.0 with only registry.npmjs.org granted, npm_health still returned HTTP 200, with weeklyDownloads: null and no error: the download counts come from api.npmjs.org. A missing variable is worse. oam removes a non-granted variable from process.env instead of throwing, so a denied NPM_TOKEN looks like no token at all, "unauthenticated" rather than "denied".
Alternate MCP clients:
Client | Config file |
Claude Code |
|
Claude Desktop |
|
Cursor |
|
Windsurf |
|
VS Code |
|
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
Operation | Preferred path | Why |
Read (search/view/stats) | These MCP tools, no auth | Fast, zero friction |
Deprecate / dist-tag / unpublish |
| HTTP API, no CLI 2FA friction with a 2FA-bypass token |
Owner / access / team / org / token changes |
| Since 2026-07-31 these need an interactive 2FA challenge; on 401/403 the error names the |
Publish |
| This repo has no CI release workflow (removed in b2c256c). Note: workstation publishes carry no sigstore provenance — |
Unpublish |
| Safer than CLI; irreversible within 72h |
CLI fallback | The | On a 401/403 from a change that needs interactive 2FA, or a 422 whose message names it |
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" }) // ...etcRotate 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 401 — what's wrong?"
→ npm_verify_token() // Confirms token scope, packages, 2FA state
→ npm_ops_playbook() // Returns the canonical retry sequenceTroubleshooting
"Error: NPM_TOKEN is required"
The tool you called needs auth. Add
NPM_TOKENto theenvblock 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.An OTP challenge arrives as a 401 and a 2FA-policy refusal as a 403; neither is ever a 422. For deprecate, undeprecate, dist-tag and unpublish, a Granular Access Token with 2FA bypass enabled fixes both. Classic tokens, including Automation tokens, were revoked in December 2025.
Owner, access, team membership and grant, org membership and token changes need an interactive 2FA challenge since 2026-07-31, even from a token with 2FA bypass. No token fixes those: the error names the exact
npmcommand for a human to run and answer the one-time-password prompt.
"HTTP 422 Unprocessable" on a write
Read the
Raw:body at the end first; it is the registry's actual reason. Before it, the message says what that call sent and the documented npm rules it could have broken, then (where one exists) the npm CLI equivalent, which prints the registry's full error and prompts for a one-time password if needed.For
npm_deprecate, aversionRangethat matches no published version and a message over 1024 characters are both rejected locally as HTTP 400 before any write, so neither is a 422 cause. The range error lists the published versions; correct the range from that list or withnpm_versions.Message punctuation is not a cause. Swapping a trailing period for an em-dash will not clear a 422.
Windows: MCP server doesn't start
Use the
cmd /c npx ...pattern from the Quick start section. Node 20+ can't spawn.cmdfiles directly.
Requirements
Node.js 20.11+ (
package.jsondeclaresengines.node: ">=20.11.0")(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 --testSee CONTRIBUTING.md for the full workflow, including release process.
License
MIT
Available Tools
64 toolsnpm_access_setADestructiveIdempotent
Set package access level: 'public' or 'restricted' (private). 'private' is accepted as an alias for 'restricted' for ergonomics -- both map to the registry wire value 'restricted'. Unscoped packages are always public. Restricted access requires a paid npm account.
Inputs: name (required), access (required).
npm_access_set_mfaADestructiveIdempotent
Configure 2FA requirement for publishing: 'none' (off), 'publish' (2FA required), 'automation' (2FA required but automation tokens can bypass).
Inputs: name (required), level (required).
npm_auditARead-onlyIdempotent
Quick vulnerability check for specific packages and versions using the bulk advisory API. Returns matching advisories with severity, CVEs, and patched versions. For richer detail (CVSS scores, CWEs, fix recommendations), use npm_audit_deep instead.
Inputs: packages (required).
npm_audit_deepARead-onlyIdempotent
Full security audit on a dependency set — returns detailed advisories with CVSS scores, CWEs, affected version ranges, fix recommendations, and full vulnerability metadata. Uses the npm audit v1 endpoint which provides richer detail than the bulk advisory API (npm_audit). Requires you to provide the dependency map (use npm_dependencies to get it first).
Inputs: name (required), dependencies (required), version.
npm_check_authARead-onlyIdempotent
Quick auth health check — returns structured data about npm auth status, token capability, and whether headless (CI/agent) publishing is possible. Run this BEFORE attempting any publish operation. Returns canPublishHeadless boolean and a clear recommendation.
MCP servers are called by AI agents which CANNOT open browsers or enter OTP codes. This tool detects that and provides the exact terminal command for the human to run instead of suggesting unworkable retries.
Inputs: no named parameters.
npm_collaboratorsARead-onlyIdempotent
Get all users who have access to a package and their permission levels (read-only, read-write). Useful for verifying who can publish to a package before setting up CI/CD.
Inputs: name (required).
npm_compareARead-onlyIdempotent
Compare 2-5 packages side-by-side — downloads, version, license, maintainers, size, last publish, and security status. Great for 'should I use X or Y?' decisions.
Inputs: packages (required).
npm_dependenciesARead-onlyIdempotent
Get the dependency lists for a specific package version — production deps, devDeps, peerDeps, and optionalDeps.
Inputs: name (required), version.
npm_deprecateADestructiveIdempotent
Deprecate a package or specific versions. Shows a warning message on install. Uses the HTTP API with NPM_TOKEN, so no CLI login or OTP prompt is involved; a token without 2FA bypass is refused with 401 or 403. Registry hard limit: deprecation messages must be <= 1024 characters. A message over the limit, or a versionRange matching no published version, is rejected locally as HTTP 400 before any write; a 422 from the registry describes the packument that was sent. Message punctuation is never checked.
Inputs: name (required), message (required), versionRange.
npm_dep_treeARead-onlyIdempotent
Resolve the production dependency tree for a package version (up to a configurable depth). Shows the full transitive dependency graph with versions. Issues one registry request per discovered package (10 in flight), so a wide tree at depth 4-5 can take a while; the walk is capped at 60s and returns truncated: true with a warning if it runs out of budget.
Inputs: name (required), depth, version.
npm_dist_tag_removeADestructiveIdempotent
Remove a dist-tag from a package. The 'latest' tag cannot be removed, only reassigned.
Inputs: tag (required), name (required).
npm_dist_tagsARead-onlyIdempotent
Get dist-tags for a package (latest, next, beta, etc).
Inputs: name (required).
npm_dist_tag_setADestructiveIdempotent
Point a dist-tag (e.g. 'latest', 'beta', 'next') at a specific version. Common uses: promote a beta to latest, roll back latest to a prior version, maintain separate channels.
Inputs: tag (required), name (required), version (required).
npm_downloadsARead-onlyIdempotent
Get total download count for a package over a period (last-day, last-week, last-month, last-year, or a custom date range like 2025-01-01:2025-12-31).
Inputs: name (required), period.
npm_downloads_bulkARead-onlyIdempotent
Compare download counts for multiple packages over a period. Up to 128 packages. Scoped packages (@scope/name) are NOT supported by the bulk endpoint — call npm_downloads separately for each scoped package.
Inputs: packages (required), period.
npm_downloads_rangeARead-onlyIdempotent
Get daily download counts for a package over a period. Returns per-day breakdown.
Inputs: name (required), period.
npm_healthARead-onlyIdempotent
Assess the health of a package — maintenance activity, download trend, security status, deprecation, and documentation quality.
Inputs: name (required).
npm_hook_addA
Create a registry webhook. Target is 'pkg' or '@scope/pkg' for a package, '@scope' for a scope, or '~user' for a user's packages. Endpoint is the HTTPS URL to POST events to; secret is used to HMAC-sign payloads. The secret is never echoed back in tool responses.
Inputs: secret (required), target (required), endpoint (required).
npm_hook_getARead-onlyIdempotent
Get a single webhook by its ID. The stored secret is redacted from the response.
Inputs: id (required).
npm_hook_listARead-onlyIdempotent
List webhooks. Optionally filter by package name. Secrets are redacted from responses.
Inputs: limit, offset, package.
npm_hook_removeADestructiveIdempotent
Delete a webhook by ID.
Inputs: id (required).
npm_hook_updateADestructiveIdempotent
Replace a webhook's endpoint AND signing secret. Both are required: the registry PUT overwrites the hook config, so this call always rotates the secret to whatever you pass — supply the current secret if you only mean to change the endpoint. The returned hook object has the secret redacted.
Inputs: id (required), secret (required), endpoint (required).
npm_license_checkARead-onlyIdempotent
Check the license of a package and its direct production dependencies. Flags missing or non-standard licenses. Matches single SPDX license identifiers case-insensitively (so 'mit' and 'MIT' both match). SPDX expressions like '(MIT OR Apache-2.0)' are NOT decomposed — they are flagged unless added to allowed verbatim. Issues 2 requests per direct dependency (10 in flight), capped at 60s; deps not reached in time come back as NOT_CHECKED (and are flagged, never treated as allowed).
Inputs: name (required), allowed, version.
npm_maintainersARead-onlyIdempotent
Get current maintainers and their publish history for a package.
Inputs: name (required).
npm_ops_playbookARead-onlyIdempotent
Return canonical recipes for common npm operations — which MCP tool to call for which op, CLI fallbacks when the MCP server can't handle something, and message format guidance. Call this FIRST when you're not sure how to do an npm operation. Prevents reinventing approaches that don't work.
Inputs: no named parameters.
npm_org_member_removeADestructiveIdempotent
Remove a user from an org. Their team memberships in that org are also removed. Requires confirm: true — team memberships cascade and cannot be selectively preserved.
Inputs: org (required), user (required), confirm (required).
npm_org_membersARead-onlyIdempotent
List all members of an npm organization with their roles (owner, admin, developer). Requires authentication as an org member.
Inputs: org (required).
npm_org_member_setADestructiveIdempotent
Add a user to an org or change their role. Roles: 'developer', 'admin', 'owner'. If the user is already in the org, updates the role. Omitting role keeps the member's current role: this tool reads the roster first and re-sends the existing role explicitly, because the registry DEFAULTS an omitted role to 'developer' rather than preserving it (which would silently demote an admin or owner). For a user who is not yet a member, omitting role adds them as 'developer'.
Inputs: org (required), user (required), confirm (required), role.
npm_org_packagesARead-onlyIdempotent
List all packages accessible to an npm organization with their access levels. Shows what the org owns or has been granted access to.
Inputs: org (required).
npm_org_teamsARead-onlyIdempotent
List all teams within an npm organization. Requires authentication as an org member.
Inputs: org (required).
npm_owner_addAIdempotent
Add a user as a maintainer of a package. They will have publish and write permissions. Resolves the user's email via /-/user/ (no need to supply it). Use npm_collaborators to verify before adding.
Inputs: name (required), username (required).
npm_owner_removeADestructiveIdempotent
Remove a user from a package's maintainer list. Refuses if it would leave the package with zero maintainers (lockout prevention).
Inputs: name (required), username (required).
npm_packageARead-onlyIdempotent
Get package metadata — description, dist-tags, latest version, maintainers, license, repository, keywords. Does not include per-version details (use npm_version for that).
Inputs: name (required).
npm_package_accessARead-onlyIdempotent
Get package access settings — visibility (public/private), whether publish requires 2FA, and whether automation tokens can bypass 2FA. Critical for understanding why CI publishing fails: if publish_requires_tfa is true but automation_token_overrides_tfa is false, automation tokens cannot publish.
Inputs: name (required).
npm_profileARead-onlyIdempotent
Get the authenticated user's npm profile — name, email, 2FA status, creation date. Useful for checking whether 2FA is enabled (which affects token requirements for publishing).
Inputs: no named parameters.
npm_provenanceARead-onlyIdempotent
Retrieve Sigstore attestations for a specific package version. Shows SLSA provenance (which CI built it, from which repo/commit) and publish attestations. NOTE: this tool RETRIEVES attestations from the registry -- it does NOT perform cryptographic signature, certificate-chain, or Rekor transparency-log verification. Use a dedicated Sigstore client to cryptographically verify the bundles.
Inputs: name (required), version (required).
npm_publish_preflightARead-onlyIdempotent
Comprehensive pre-publish validation — run before publishing ANY npm package. Returns an actionable checklist with pass/fail/warn for each item.
ASSUMES NON-INTERACTIVE CONTEXT BY DEFAULT because MCP servers are called by AI agents that:
CANNOT open browsers (so --auth-type=web is useless)
CANNOT enter OTP codes
CANNOT retry with 2FA — this is a hand-off to the human
Checks: auth token validity, 2FA requirements, token type inference, org-level token reuse, package name availability, maintainer access, scoped package settings.
When issues are found, returns structured actions with exact commands for the HUMAN to run in their terminal — never suggests actions an agent cannot perform.
Inputs: name (required).
npm_readmeBRead-onlyIdempotent
Get the README content of a package.
Inputs: name (required).
npm_recent_changesARead-only
Get the most recent package publishes/updates from the npm registry via the CouchDB changes feed. Note: uses replicate.npmjs.com which may have intermittent availability.
Inputs: limit.
npm_registry_statsARead-onlyIdempotent
Get total npm-wide download counts for a period. Shows overall registry activity.
Inputs: period.
npm_release_frequencyARead-onlyIdempotent
Analyze the release cadence of a package — publish timeline, gaps, and whether the project is actively maintained.
Inputs: name (required), limit.
npm_searchARead-onlyIdempotent
Search the npm registry for packages. Supports text search and qualifiers like 'keywords:mcp', 'author:user', 'maintainer:user', 'scope:org', 'not:insecure', 'is:unstable'.
Inputs: query (required), from, size, quality, +2 more.
npm_signing_keysARead-onlyIdempotent
Get the npm registry's ECDSA signing keys used to verify package signatures.
Inputs: no named parameters.
npm_team_createB
Create a team inside an organization. Team is passed as '@scope:team'.
Inputs: team (required), description.
npm_team_deleteADestructiveIdempotent
Delete a team. Team is passed as '@scope:team'. Revokes all package permissions that team held, and team memberships are also removed. Requires confirm: true — this removes the team and all its package grants in one call. List the team's current grants with npm_team_packages first if you need to preserve them.
Inputs: team (required), confirm (required).
npm_team_grantADestructiveIdempotent
Grant a team read-only or read-write permission on a package. Scope and team are passed as @scope:team (e.g. '@yawlabs:devs'). Requires org admin or team admin.
Inputs: team (required), package (required), permissions (required).
npm_team_member_addAIdempotent
Add a user to a team. Team is '@scope:team'. User must already be in the org.
Inputs: team (required), user (required).
npm_team_member_removeADestructiveIdempotent
Remove a user from a team. Team is '@scope:team'. User remains in the org.
Inputs: team (required), user (required).
npm_team_membersARead-onlyIdempotent
List all members of a team with their roles (e.g. 'developer'). Complements npm_team_member_add and npm_team_member_remove — use this to audit who is currently on the team before adding or removing members.
Inputs: org (required), team (required).
npm_team_packagesARead-onlyIdempotent
List all packages a specific team has access to and their permission levels (read-only or read-write). Useful for auditing team permissions.
Inputs: org (required), team (required).
npm_team_revokeADestructiveIdempotent
Revoke a team's access to a package. Team is passed as '@scope:team'. Does not delete the team itself — use npm_team_delete for that.
Inputs: team (required), package (required).
npm_token_revokeADestructiveIdempotent
Revoke an access token by its key (UUID from npm_tokens). Requires confirm: true. Revoking the token currently in use by NPM_TOKEN will break the next call. Creating tokens is NOT exposed because the endpoint requires the user password — create via https://www.npmjs.com/settings/~/tokens instead.
Inputs: confirm (required), tokenKey (required).
npm_tokensARead-onlyIdempotent
List all access tokens for the authenticated npm user. Shows token type, creation date, CIDR restrictions, and read-only status. Critical for finding reusable automation/granular tokens that cover your org scope — avoids the common mistake of creating duplicate tokens or using publish tokens in CI (which still require OTP).
Inputs: page, perPage.
npm_trusted_publishersARead-onlyIdempotent
List trusted publishing configurations for a package. Shows OIDC trust relationships with CI/CD providers (GitHub Actions, GitLab CI, CircleCI) that allow tokenless publishing. Requires authentication with write access to the package.
Inputs: name (required).
npm_typesARead-onlyIdempotent
Check TypeScript type support for a package — whether it ships built-in types (types/typings field) or has a DefinitelyTyped companion (@types/* package).
Inputs: name (required), version.
npm_undeprecateADestructiveIdempotent
Clear the deprecation message from a package or specific versions. Equivalent to npm_deprecate with an empty message but more explicit about intent.
Inputs: name (required), versionRange.
npm_unpublish_packageADestructive
Unpublish an ENTIRE package (all versions). DELETE /{pkg}/-rev/{rev}. IRREVERSIBLE: the name is blocked for 72 hours and cannot be re-published. For single-version unpublish prefer npm_unpublish_version. Requires confirm: true.
Inputs: name (required), confirm (required).
npm_unpublish_versionADestructive
Unpublish a specific version of a package. IRREVERSIBLE: once unpublished, the version cannot be re-published and will be blocked for 72 hours. Only works within 72 hours of the original publish for most packages. Requires explicit confirm: true to prevent accidents. Follows the npm CLI flow (mutate packument + delete tarball). For full-package unpublish use npm_unpublish_package. Dist-tag handling: any dist-tag that pointed at the unpublished version is removed. Only latest is auto-reassigned (to the highest remaining stable version). Other tags like next/beta are left unset — reassign them explicitly with npm_dist_tag_set if needed.
Inputs: name (required), confirm (required), version (required).
npm_user_packagesBRead-onlyIdempotent
List all packages published by a specific npm user. Shows package names and the user's access level for each. Requires authentication.
Inputs: username (required).
npm_verify_tokenARead-onlyIdempotent
Verify the NPM_TOKEN and surface its capabilities — username, 2FA status, and whether writes are likely to succeed. Call this FIRST when debugging any write failure to rule out auth issues before trying other fixes. Faster than running writes and interpreting 401/403 errors.
Inputs: no named parameters.
npm_versionARead-onlyIdempotent
Get detailed metadata for a specific version — dependencies, dist info, file count, size, deprecation status.
Inputs: name (required), version.
npm_version_downloadsARead-onlyIdempotent
Get download counts broken down by version for the last week. Shows version adoption.
Inputs: name (required), period.
npm_versionsARead-onlyIdempotent
List published versions of a package with their publish dates, ordered newest first. Returns up to limit versions (default 50). Set limit=0 to return all.
Inputs: name (required), limit.
npm_whoamiARead-onlyIdempotent
Check the currently authenticated npm user. Verifies the NPM_TOKEN is valid and returns the associated username. Essential for debugging auth issues before publishing.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 64 tools
Most tools target distinct resources and actions, with clear boundaries between metadata, downloads, security, teams, and hooks. A few auth-focused tools (npm_whoami, npm_profile, npm_verify_token, npm_check_auth) and download variants (npm_downloads, npm_downloads_range, npm_downloads_bulk) could be confused, but the descriptions help disambiguate them.
The npm_ prefix and snake_case are consistent, and most tools follow a resource-first pattern (npm_team_create, npm_hook_add, npm_dist_tag_set). However, a handful of action-first verbs (npm_search, npm_compare, npm_audit) and bare nouns (npm_health, npm_tokens) break the pattern, creating minor inconsistency.
64 tools is far beyond the well-scoped 3-15 range. Even for the broad npm registry API, this is excessive; an agent must parse many near-synonymous entries, and several groups (downloads variants, auth checks, team management) could be consolidated into fewer, more parameterized tools.
The server covers most of the npm registry domain: metadata, search, downloads, security, auth, teams, orgs, hooks, dist-tags, and unpublishing. The main gap is the absence of an actual npm_publish tool (only npm_publish_preflight exists), and token creation is deliberately omitted, so publishing workflows require a human handoff.
Maintenance
Related MCP Connectors
Dive into the world of npm with our NPM Package Info MCP. Access crucial metadata about any npm
Provide AI-powered real-time analysis and intelligence on NPM packages, including security, depend…
Unofficial npm MCP — wraps the npm Registry API (free, no auth)
Live npm and UNPKG data for AI agents: resolution, audits, import maps, malware/CVE checks.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to interact with the npm registry, covering package intel, dist-tags, trusted publisher configuration, access and team governance, tokens, security advisories, and publishing, with read-only tools by default.312 npmMIT
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code and other MCP clients to retrieve real-time documentation, type signatures, and code examples for any npm package, with intent-aware formatting, version and migration diffs, error diagnosis, package comparison, and dependency scanning. Results are pulled on demand from npm, CDNs, and GitHub with BM25 search over 25 concept synonym clusters and production-grade caching and retry logic.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code and other MCP clients to retrieve context-aware documentation, type signatures, and code examples for any npm package, along with cross-version migration guides, error diagnosis, package comparison, and dependency scanning. Results are formatted to match query intent and drawing on real package types, changelogs, and GitHub docs.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to access real-time, context-aware documentation, TypeScript types, code examples, version and migration insights, error diagnoses, package comparisons, and dependency scans for any npm package through MCP.-