npm Registry MCP Server

Search the npm registry for packages. Supports text search and qualifiers like 'keywords:mcp', 'author:user', 'maintainer:user', 'scope:org', 'not:insecure', 'is:unstable'.

Get package metadata — description, dist-tags, latest version, maintainers, license, repository, keywords. Does not include per-version details (use npm_version for that).

Get detailed metadata for a specific version — dependencies, dist info, file count, size, deprecation status.

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.

Get the README content of a package.

Get dist-tags for a package (latest, next, beta, etc).

Check TypeScript type support for a package — whether it ships built-in types (types/typings field) or has a DefinitelyTyped companion (@types/* package).

Get the dependency lists for a specific package version — production deps, devDeps, peerDeps, and optionalDeps.

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.

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).

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).

Get daily download counts for a package over a period. Returns per-day breakdown.

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.

Get download counts broken down by version for the last week. Shows version adoption.

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.

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).

Get the npm registry's ECDSA signing keys used to verify package signatures.

Takes no parameters.

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.

Assess the health of a package — maintenance activity, download trend, security status, deprecation, and documentation quality.

Get current maintainers and their publish history for a package.

Analyze the release cadence of a package — publish timeline, gaps, and whether the project is actively maintained.

Get total npm-wide download counts for a period. Shows overall registry activity.

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.

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.

Takes no parameters.

Check the currently authenticated npm user. Verifies the NPM_TOKEN is valid and returns the associated username. Essential for debugging auth issues before publishing.

Takes no parameters.

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).

Takes no parameters.

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).

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.

Takes no parameters.

List all packages published by a specific npm user. Shows package names and the user's access level for each. Requires authentication.

List all members of an npm organization with their roles (owner, admin, developer). Requires authentication as an org member.

List all packages accessible to an npm organization with their access levels. Shows what the org owns or has been granted access to.

List all teams within an npm organization. Requires authentication as an org member.

List all packages a specific team has access to and their permission levels (read-only or read-write). Useful for auditing team permissions.

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.

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.

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.

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.

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.

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.

Takes no parameters.

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.

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.

Clear the deprecation message from a package or specific versions. Equivalent to npm_deprecate with an empty message but more explicit about intent.

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.

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.

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.

Remove a dist-tag from a package. The 'latest' tag cannot be removed, only reassigned.

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.

Remove a user from a package's maintainer list. Refuses if it would leave the package with zero maintainers (lockout prevention).

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.

Configure 2FA requirement for publishing: 'none' (off), 'publish' (2FA required), 'automation' (2FA required but automation tokens can bypass).

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.

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.

Create a team inside an organization. Team is passed as '@scope:team'.

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.

Add a user to a team. Team is '@scope:team'. User must already be in the org.

Remove a user from a team. Team is '@scope:team'. User remains in the org.

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'.

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.

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.

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.

List webhooks. Optionally filter by package name. Secrets are redacted from responses.

Get a single webhook by its ID. The stored secret is redacted from the response.

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.

Delete a webhook by ID.