NPMScan plugin for Claude Code

A Claude Code plugin that gives Claude read-only npm package and vulnerability lookups, backed by npmscan.com's free, unauthenticated MCP server.

Direct links

Claude (Anthropic plugin directory): claude.ai/customize/skills/…/npmscan
ChatGPT (OpenAI plugins directory): chatgpt.com/plugins/…/npmscan
Setup docs for other clients: npmscan.com/mcp

What it adds

MCP server (npmscan, https://npmscan.com/api/mcp) with twenty-three tools — see Tools below. Every tool result includes an npmscanUrl linking back to the full write-up on npmscan.com. No API key or auth required — same public data as the website. The server is stateless and rate-limited to 30 requests/minute per IP. Every vulnerability finding carries isMalware, so a confirmed-malicious package is reported as malware to remove, never as an ordinary bug.
/npmscan:dependency-audit skill — chains batch_query_vulnerabilities → get_package/get_package_version → analyze_transitive_dependencies → the maintainer/provenance/license/remediation/alternative tools into one dependency-audit report, instead of leaving that tool sequencing to Claude each time. Also handles PR-style before/after diffs via diff_dependencies, raw npm audit --json output via enrich_npm_audit, and a bare GitHub repo URL via audit_github_repository. Triggers automatically when you paste a package.json/lockfile/SBOM, give a GitHub repo URL, or ask to check/audit your dependencies, or invoke it directly. See skills/dependency-audit/SKILL.md.
/npmscan:package-trust-check skill — a deep, single-package investigation for "is X safe / was X compromised" questions: a malware check (including versions npm has since removed for being malicious), maintainer add/remove history (account-takeover patterns), publish-provenance cross-checks, and install-script scanning, in one report. Triggers automatically on a trust question about one named package; not for auditing a whole dependency list (that's dependency-audit). See skills/package-trust-check/SKILL.md.
/npmscan:new-dependency-evaluation skill — for a forward-looking choice about what to add, not what's already installed: comparing 2-5 named candidates ("axios vs got vs node-fetch"), evaluating one candidate against its real peers, or shortlisting candidates from a described need. Orchestrates compare_packages/suggest_alternative/search_packages into a structured side-by-side with a deterministic pick. See skills/new-dependency-evaluation/SKILL.md.
/npmscan:incident-response skill — turns an existing finding, or just a vague symptom description ("npm install did something weird"), into concrete get_remediation_playbook steps: real incident references, severity, and prevention tips, not improvised advice. See skills/incident-response/SKILL.md.
/npmscan:ci-pr-gate skill — turns a dependency change (a before/after snapshot, or one or more named "bump X from A to B" upgrades) into one deterministic PASS/WARN/FAIL verdict formatted for a CI check or PR-comment bot, applying a fixed policy on top of diff_dependencies/simulate_dependency_upgrade — not a conversational report (that's dependency-audit's job). See skills/ci-pr-gate/SKILL.md.

Tools

NPMScan provides twenty-three tools:

Tool	Description
`search_packages`	Search the npm registry by name or keywords. Each result includes weekly/monthly download counts, dependent-package counts, and rank among npmscan's own top-100k-by-downloads snapshot, so you can tell an established package from an abandoned or squatted one that merely matches the query text — flags `possibleTyposquatOf` when a low-popularity result's name is one typo away from a top-5,000 package.
`get_package`	Latest version, install scripts (`preinstall`/`install`/`postinstall`/`prepare`), maintainers, license, recent version history, weekly downloads, GitHub stars, TypeScript support, days since last publish, ecosystem-wide download rank, a 3-month download trend, and an `isLatestVersionVulnerable`/`highestSeverity` verdict (with fixed versions and `isMalware` per finding) — plus a rule-based (not model-generated) maintenance/popularity summary and typosquat flag computed from those numbers.
`get_package_version`	Metadata for one exact version plus an OSV.dev check scoped to that version — `isVulnerable`/`highestSeverity` as a direct safe/not-safe answer, with each finding's severity, summary, fixed version and `isMalware`. For checking a version pinned in a lockfile. A version npm has removed but OSV still has advisories for (usually one pulled for being malicious) comes back with `versionExists: false` and those findings, not a bare "not found".
`get_maintainer_profile`	Packages an npm username currently maintains via npm's own `maintainer:<username>` search index, plus precomputed download/dependent totals across all of them. Lists the most-downloaded `limit` packages (default 50, max 250); totals still cover every package found. A plain info lookup, not a security check — pair it with `check_maintainer_blast_radius` for the actual compromised-account signal.
`query_vulnerabilities`	OSV.dev lookup for known vulnerabilities affecting a package, optionally scoped to a version, with `isVulnerable`/`highestSeverity` as a direct verdict and each finding's severity, summary, fixed version and `isMalware`. For npm it also cross-checks the name/version against the registry: a name or version that isn't on npm still returns its OSV data, with `packageExists: false` and an `existenceCheckNote` — so a typo doesn't read as "clean", and a version removed for malware still shows its findings. Accepts `packageName` as an alias for `name`, and other ecosystems via `ecosystem` (e.g. `"PyPI"`).
`batch_query_vulnerabilities`	OSV.dev lookup across a whole dependency inventory at once — pass a flat `packages` list, or paste raw `package.json`/lockfile/CycloneDX JSON/SPDX JSON content via `content` and it parses that for you. Chunks large inventories internally, with severity, summary, CVE aliases, fixed version and `isMalware` per finding. Also reports names/versions that aren't on npm (`unresolvedPackages`/`nonexistentVersions` — never read those as clean), per-package `signals` (deprecated, install scripts, popularity, typosquat), and for lockfiles a `source` check that flags a tarball from an unexpected host or one that is a different package than declared (`identityMismatch`).
`get_latest_advisories`	Recently published npm advisories from one of three sources (one per call): `type: "reviewed"` (default) is GitHub's curated, mostly CVE-backed set, filterable by severity, vulnerability category, affected package name, or an exact GHSA/CVE ID; `type: "malware"` is GitHub's own malicious-package advisories; `type: "osv"` is OSV.dev's OpenSSF malicious-packages feed (`MAL-` ids). Cursor-paginated. These are feeds of recent advisories, not a package's full history — to check whether a package is or was malware, use `query_vulnerabilities` and its `isMalware` flags.
`get_cve`	NIST NVD lookup for one exact CVE ID (authoritative CVSS score/vector, CWEs, references), or a keyword/severity/CWE/date-range search. Enriched with CISA KEV status (actively exploited in the wild?) and FIRST.org EPSS (30-day exploitation probability). Falls back to the raw MITRE CVE record when NVD has no data yet. Not npm-scoped — NVD covers every ecosystem.
`analyze_install_script`	Fetches a package's published tarball and statically scans its `preinstall`/`install`/`postinstall`/`prepare` lifecycle scripts — and the files they reference, pulled from the tarball itself — against npmscan's red-flags rubric (`child_process` use, network calls, sensitive-path/env access, obfuscation, untrusted remote binaries, exfil hosts, eval on decoded strings, CI telemetry) plus a typosquat check. Returns a `totalScore` and `riskTier`. A `prepare`-only package scores 0 unless its command does something alarming, since npm never runs a dependency's `prepare` on install. A heuristic static scan, not proof of malice — it doesn't execute code or check maintainer history.
`analyze_transitive_dependencies`	Recursively resolves 1-15 direct/root packages' dependency graphs to a configurable depth (default 2, max 3) and batch-checks every resolved package against OSV.dev — surfaces vulnerabilities buried several levels deep that a flat `batch_query_vulnerabilities` call would miss, with `vulnerablePaths` naming which direct dependency pulled in each vulnerable transitive package. A total-node budget caps runaway graphs, reported via `truncated`/`truncationNote` rather than silently returning a partial scan as complete.
`check_package_provenance`	Checks a version's npm/Sigstore publish provenance against reality: flags a non-GitHub-hosted builder or an attested source repo that doesn't match `package.json`'s own `repository` field; flags a package missing provenance while its npm-scope/maintainer peers consistently have it (skipped for versions published before npm provenance existed, 2023-04-19); and diffs the published tarball's install scripts/dependencies against the source repository at the attested commit — the pattern of a stolen-npm-token publish that bypasses CI. For a version npm has removed, the error names any OSV advisories for it. Structural only, not a cryptographic re-verification of the Sigstore bundle.
`check_maintainer_changes`	Reconstructs a package's maintainer-add/remove history from the npm packument and flags account-takeover patterns — a new maintainer who published shortly after being added, a sudden full maintainer-list replacement, a long-standing maintainer quietly dropped, or a maintainer change not yet tied to any release. Also cross-checks the declared GitHub repository for transfers/archival.
`check_maintainer_blast_radius`	Given an npm username, finds the packages that account currently maintains and flags a tight cluster of packages published within a short rolling window of each other — the compromised-account pattern behind incidents like the 2025 chalk/debug ("qix") compromise and the 2026 keyv/cacheable ("Shai-Hulud") worm. Clusters over a year old count for a quarter, as do clusters at least 30 days old whose versions have no malware advisory, and clusters of near-unused packages don't count. A large total package count alone is never the signal. Lists the most-downloaded `limit` packages (default 50), always including every package in a cluster.
`get_remediation_playbook`	Maps a finding's `rule` value from `analyze_install_script`/`check_maintainer_changes`/`check_package_provenance` (or an `id` slug guessed from a plain-language description) to a human-authored incident-response playbook — concrete steps, severity, real-incident references, and prevention tips, not just a link. Includes `compromised-publisher` for when your own npm account or tokens were used to publish malware (token revocation, credential rotation, deprecating the bad versions). Pure local lookup, batches up to 10 rules per call.
`check_license_compliance`	Given a package list and an optional allow/deny license policy, classifies each declared SPDX license (permissive/weak-copyleft/copyleft/network-copyleft/proprietary/public-domain/unknown), understands simple SPDX expressions (`OR`/`AND`/`WITH`), and reports a compliance verdict per package. With no policy given, applies a default rule flagging only copyleft/network-copyleft/proprietary. Ambiguous expressions are reported as `needsReview`, not silently guessed at.
`diff_dependencies`	Compares two raw snapshots of a `package.json`, `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` — e.g. before/after a PR — and reports added/removed/version-bumped packages. For every added or bumped package: a newly introduced `preinstall`/`install`/`postinstall` script (`installScriptIntroduced`; a new `prepare` is listed but never runs on a registry install), `vulnerabilityDelta` (introduced/fixed/still-vulnerable/still-clean), `sourceIntegrityChanged` (same version, different tarball or hash — `changeType: "source-swap"`), and `identityMismatch` (the tarball is a different package or version than declared, with vulnerabilities checked for the real one). Also diffs the project's own root lifecycle scripts and overrides. Ideal for a CI gate reviewing a dependency-changing PR.
`prioritize_remediation`	Given a batch of already-flagged vulnerability findings, ranks them by what to actually fix first, into a `remove-now`/`patch-now`/`patch-soon`/`scheduled`/`monitor` tier per finding. Confirmed malware (a `MAL-` id, or an advisory whose OSV record is a malware advisory — looked up automatically) is `remove-now`; CISA KEV status (active exploitation) is `patch-now`; otherwise FIRST.org EPSS (30-day exploitation probability) leads, with severity as a fallback, and an EPSS of 10% or more is at least `patch-soon`. A fix-order ranking across a backlog, not a merge gate.
`simulate_dependency_upgrade`	Classifies a specific version jump (e.g. a suggested `fixedVersion`) as safe/low-risk/review-recommended/breaking-change-likely/unknown/do-not-upgrade by semver bump, a newly-deprecated target, a newly-introduced `preinstall`/`install`/`postinstall` script, a tightened Node engine requirement, and a before/after OSV.dev check reporting `vulnerabilityDelta`. `do-not-upgrade` means the target is known malware, or npm no longer lists it while OSV still has advisories for it. Accepts a single `packageName` (or `name`)/`currentVersion`/`targetVersion`, or a `packages` batch of up to 100 upgrades in one call. Doesn't fetch changelogs or diff source — a fast deterministic pre-check.
`suggest_alternative`	Suggests better-maintained replacements for a deprecated, vulnerable, abandoned, or suspicious package by combining maintainer-provided deprecation hints, a hand-checked list of known successors for well-known packages (e.g. `request` → got/undici/ky, `colors` → @colors/colors), and deterministic npm search/category ranking — filtering out typosquats, deprecated, vulnerable and unverifiable candidates, and returning plain-language `whySuggested` notes, or a `nonPackageAlternatives` entry when a language built-in supersedes the package entirely.
`compare_packages`	Given 2-5 candidate packages for the same job (e.g. "axios vs got vs node-fetch"), fans the same registry/popularity/maintenance/vulnerability enrichment `get_package` computes out across every candidate in parallel, adds a lightweight install-script risk signal (a `prepare`-only candidate isn't penalized) and an install-size rollup (own + transitive), and returns a structured side-by-side plus a deterministic, reasoned pick — never a deprecated or typosquat-flagged candidate. A name that fails to resolve still appears with `found:false` rather than failing the whole call.
`audit_github_repository`	Given a GitHub repo URL, fetches its `package.json`/lockfile from the default branch (auto-detecting monorepos via workspace globs) and checks every lockfile entry for known vulnerabilities, then gives up to 100 packages — vulnerable ones first — the license-compliance, install-script and, for up to 5 elevated-risk packages (one slot per package, not per version), ownership-risk checks, in one call, no copy-pasting file contents required. `coverage` and a summary starting `PARTIAL AUDIT` say when not everything got every check. The most expensive tool in the suite; avoid calling it in a tight loop across many repos.
`generate_sbom`	Generates a spec-valid CycloneDX or SPDX SBOM from the same `packages`/`content` inputs `batch_query_vulnerabilities` accepts, with npmscan's own vulnerability and license findings embedded in each format's native fields (CycloneDX's top-level `vulnerabilities[]`, SPDX's `externalRefs[]`). Every finding's VEX state is `in_triage` — an honest "OSV/GHSA match found, not manually assessed," never a stronger claim.
`enrich_npm_audit`	Ingests raw `npm audit --json` output directly (npm 7+ or legacy npm 6 format) and ranks it with the same CISA KEV + FIRST.org EPSS + severity scoring as `prioritize_remediation`, resolving each finding's GHSA advisory to a CVE alias first (npm audit JSON almost never carries a CVE id on its own). `yarn audit --json`/`pnpm audit --json` are rejected rather than misparsed — use `batch_query_vulnerabilities` with the manifest/lockfile for those.

Install

Option 1: add this repo as a marketplace

/plugin marketplace add salemalem/npmscan-mcp-plugin
/plugin install npmscan@npmscan
/reload-plugins

Option 2: point Claude Code at a local checkout

claude --plugin-dir ./npmscan-mcp-plugin

Useful for testing changes before pushing them.

Option 3: skip the plugin, add the MCP server directly

If you only want the tools (no bundled skills), you don't need this repo at all:

claude mcp add --transport http npmscan https://npmscan.com/api/mcp

or in .mcp.json / ~/.claude.json:

json

{
  "mcpServers": {
    "npmscan": {
      "type": "http",
      "url": "https://npmscan.com/api/mcp"
    }
  }
}

(The "type": "http" field is required — Claude Code treats an entry with a url but no type as misconfigured and skips it.)

Try it

Does lodash have any known vulnerabilities?
Find npm packages for parsing CSV files
Before I install left-pad, tell me about its maintainers and install scripts.
Is chalk 5.6.1 safe? I heard there was a supply-chain incident.
What changed between these two package-lock.json snapshots?
Should we use axios, got, or node-fetch for our new HTTP client?
Audit https://github.com/expressjs/express for dependency issues.

Or paste a package.json and ask "audit my dependencies for vulnerabilities."

Repo layout

npmscan-mcp-plugin/
├── .claude-plugin/
│   ├── plugin.json        # plugin manifest
│   └── marketplace.json   # lets this repo be added directly as a marketplace
├── .mcp.json               # bundles the npmscan MCP server
├── README.md
├── CHANGELOG.md            # what changed in each plugin version
├── SUBMISSION.md           # values for the plugin-directory submission form
├── LICENSE
├── kimi.plugin.json        # Kimi plugin manifest (ignored by Claude Code)
├── icon.png                # Kimi plugin icon (dark tile, npmscan.com branding)
├── locales/                # Kimi interface translations (zh-CN)
│   └── zh-CN.json
├── KIMI.md                 # Kimi test results + submission steps
└── skills/                 # shared by both clients; generated, don't edit here (see below)
    ├── dependency-audit/
    │   ├── SKILL.md
    │   └── references/test-prompts.md
    ├── package-trust-check/
    │   ├── SKILL.md
    │   └── references/test-prompts.md
    ├── new-dependency-evaluation/
    │   ├── SKILL.md
    │   └── references/test-prompts.md
    ├── incident-response/
    │   ├── SKILL.md
    │   └── references/test-prompts.md
    └── ci-pr-gate/
        ├── SKILL.md
        └── references/test-prompts.md

Validate and test locally

bash

claude plugin validate .
claude --plugin-dir .

Then in the session, run /npmscan:dependency-audit, /npmscan:package-trust-check, /npmscan:new-dependency-evaluation, /npmscan:incident-response, or /npmscan:ci-pr-gate (or just paste a package.json/name a package and ask) to exercise each skill, and try the prompts in each skill's references/test-prompts.md.

Submitting to a marketplace

NPMScan is already listed in Anthropic's plugin directory (see Direct links). The values used for that submission form are in SUBMISSION.md; update them there when the plugin changes.

Self-hosted (this repo): nothing further to do — anyone can /plugin marketplace add this repo directly, as shown above.
claude-plugins-community: submit via claude.ai/admin-settings/directory/submissions/plugins/new (Team/Enterprise orgs) or platform.claude.com/plugins/submit (individual authors). Run claude plugin validate . first — the review pipeline runs the same check.
claude-plugins-official: curated directly by Anthropic; there's no application form for it.

See Anthropic's plugin docs for the full development and distribution guide.

Using it with Kimi

This same repo is also a Kimi plugin: kimi.plugin.json declares the same MCP server and points at the same skills/ directory. Claude Code ignores that file, and Kimi prefers it over .claude-plugin/plugin.json, so each client reads its own manifest and both load the same five skills.

Kimi Code CLI: /plugins install https://github.com/salemalem/npmscan-mcp-plugin (or /plugins install ./ from a local checkout).
Kimi Work: in the plugin marketplace, click "Custom plugin" and ask Plugin Builder to import https://github.com/salemalem/npmscan-mcp-plugin. It appears under the Personal tab; click + to install.

The manifest is prepared for the official Kimi marketplace: full zh-CN locale, brandColor (#ef4444, npmscan.com's primary red), a dark rounded-tile icon.png built from the site's dark-mode logo, and hostKind: hosted. Kimi's local validation passed with 0 errors / 0 warnings on v3.0.2 (the last version imported into Kimi; see KIMI.md). Official-marketplace publication goes through a Kimi review step — see KIMI.md for the status and the application steps.

Test results and marketplace submission steps: KIMI.md.

When editing, keep Kimi-only settings inside kimi.plugin.json. Don't add root-level commands/, agents/, or hooks/ directories for Kimi, because Claude Code auto-loads those too.

Also available for other AI clients

The same npmscan MCP server and the same dependency-audit / package-trust-check / new-dependency-evaluation / incident-response / ci-pr-gate skills are also available in OpenAI's ChatGPT Plugins directory (submission artifacts live in the main npmscan app repo, under mcp/).

Where to edit the skills: the main npmscan repo's mcp/skills/ is the only source. This repo's skills/ folder is generated from it by npm run sync:plugin-skills (run in the main repo), which rewrites the few platform-specific sentences for Claude; npm run sync:plugin-skills -- --check fails when the two have drifted. An edit made directly in this repo's skills/ is overwritten by the next sync.