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.

NPMScan is also officially listed for both ChatGPT and Claude on
npmscan.com's MCP page, so users can verify that
this plugin points at the same public service.

Official listings

Claude (Anthropic's official Claude directory):
claude.ai/customize/skills/…/npmscan
ChatGPT (install npmscan as an app for one-click setup):
chatgpt.com/plugins/…/npmscan
mcpHQ: mcphq.org
TensorBlock MCP Index: tensorblock.co/mcp
Awesome Gemini CLI: Piebald-AI/awesome-gemini-cli
Awesome Gemini CLI Extensions: Piebald-AI/awesome-gemini-cli-extensions
Setup docs for other clients: npmscan.com/mcp

Pending:

Grok Build (xAI's official plugin marketplace): submitted in
xai-org/plugin-marketplace#1506,
awaiting xAI review. See Using it with Grok Build.
GitHub Copilot (Awesome Copilot marketplace): submitted in
github/awesome-copilot#5142.
Gemini CLI (extension gallery): indexed automatically from this repo. See
Using it with Gemini CLI.

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:

{
  "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
├── LICENSE
├── .github/plugin/
│   └── plugin.json         # GitHub Copilot plugin manifest
├── gemini-extension.json   # Gemini CLI extension manifest
├── llms-install.md         # setup steps for Cline's one-click installer
├── assets/logo-400.png     # 400×400 logo for the Cline marketplace
├── 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
├── outreach/               # directory listings: tracker, per-directory notes, scripts
└── 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

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
Official listings). The values used for that submission form
are in outreach/targets/claude.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 outreach/targets/kimi.md).
Official-marketplace publication goes through a Kimi review step — see
outreach/targets/kimi.md for the status and the application steps.

Test results and marketplace submission steps: outreach/targets/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.

Using it with Grok Build

Grok Build reads this repo as-is (.claude-plugin/plugin.json, .mcp.json
and skills/), so it needs no Grok-specific manifest.

Status: submitted to xAI's official marketplace in
xai-org/plugin-marketplace#1506
as a remote source pinned to commit 5cbf977 (v3.1.2). It's waiting for
xAI to approve the CI run and do a code-owner review. The source stays on
this personal-account repo rather than the NPMscan org, so the Claude and
ChatGPT listings don't have to move.
After merge: install with /marketplace or
grok plugin install npmscan inside Grok Build.
Updating: Grok Build installs the pinned commit only. To ship a new
release, open a PR to xai-org/plugin-marketplace that bumps the sha of
the npmscan entry in .grok-plugin/marketplace.json, then run
python3 scripts/generate-plugin-index.py, scripts/validate-catalog.py
and scripts/generate-plugin-index.py --check there. The index script
fetches every plugin in the catalog and takes several minutes.

Using it with Gemini CLI

This repo is also a Gemini CLI extension:
gemini-extension.json declares the same MCP server
(httpUrl, streamable HTTP), and Gemini CLI loads the same five skills from
skills/.

gemini extensions install https://github.com/salemalem/npmscan-mcp-plugin

The install follows main, so each push offers installed users an update.
The extension gallery finds the repo
by its gemini-cli-extension GitHub topic and re-crawls it daily; there's
nothing to submit. Check a change with
gemini extensions validate . before pushing.

Antigravity CLI users (which replaced Gemini CLI for free and Google AI
Pro/Ultra accounts) can bring the extension over with
agy plugin import gemini after installing it in Gemini CLI.

Using it with Cline

Cline connects to the hosted server directly; there's nothing to build and
no API key:

cline mcp install npmscan --transport http https://npmscan.com/api/mcp --yes

or in cline_mcp_settings.json:

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

llms-install.md has the same steps for Cline's one-click
installer. Cline's marketplace logo is
assets/logo-400.png.

Using it with Factory (Droid)

Droid installs Claude Code plugins as they are: it translates
.claude-plugin/ and .mcp.json into its own layout when it caches the
plugin. Add this repo as a marketplace, then install the plugin:

droid plugin marketplace add salemalem/npmscan-mcp-plugin
droid plugin install npmscan@npmscan-mcp-plugin --scope user

The marketplace takes its name from the repo (npmscan-mcp-plugin), not
from the name in .claude-plugin/marketplace.json, so the plugin ID is
npmscan@npmscan-mcp-plugin. Check it with droid mcp list: npmscan
should show as http connected, and the five skills come with it.

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 ChatGPT via the official
npmscan app listing
(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.

License

MIT — see LICENSE.

Made by BlockHacks.io — protecting the open source
ecosystem.