io.github.YawLabs/npmjs-mcp

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

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

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.

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.

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.

Resolve the production dependency tree for a package version (up to a configurable depth). Shows the full transitive dependency graph with versions.

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

Deprecate a package or specific versions. Shows a warning message on install. Uses the HTTP API with NPM_TOKEN, bypassing the CLI auth friction that causes 422 errors on accounts with 2FA. Registry hard limit: deprecation messages must be <= 1024 characters. If the registry 422s, first verify the semver range matches at least one published version (npm_versions) — range/version mismatches are the most common cause, not message format.

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

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.

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

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

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 daily download counts for a package over a period. Returns per-day breakdown.

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

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.

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

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

Delete a webhook by ID.

Update a webhook's endpoint and/or secret. The returned hook object has the secret redacted.

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.

Get current maintainers and their publish history for a package.

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.

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.

Add a user to an org or change their role. Roles: 'developer', 'admin', 'owner'. If user is already in the org, updates the role. Omit role to keep existing role.

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.

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

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

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.

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

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.

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.

Get the README content of a package.

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.

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

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

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 the npm registry's ECDSA signing keys used to verify package signatures.

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.

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.

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.

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.

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