NPMScan plugin for Claude Code

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

NPMScan is also officially listed for both ChatGPT and Claude onnpmscan.com's MCP page, so users can verify thatthis 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
Setup docs for other clients: npmscan.com/mcp

Pending:

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

What it adds

MCP server (npmscan, https://npmscan.com/api/mcp) withtwenty-three tools — see Tools below. Every tool result includesan npmscanUrl linking back to the full write-up on npmscan.com. No APIkey or auth required — same public data as the website. The server isstateless and rate-limited to 30 requests/minute per IP. Everyvulnerability finding carries isMalware, so a confirmed-maliciouspackage 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 onedependency-audit report, instead of leaving that tool sequencing to Claudeeach time. Also handles PR-style before/after diffs viadiff_dependencies, raw npm audit --json output via enrich_npm_audit,and a bare GitHub repo URL via audit_github_repository. Triggersautomatically when you paste a package.json/lockfile/SBOM, give a GitHubrepo 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-packageinvestigation for "is X safe / was X compromised" questions: a malwarecheck (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 onereport. Triggersautomatically on a trust question about one named package; not forauditing a whole dependency list (that's dependency-audit). Seeskills/package-trust-check/SKILL.md.
/npmscan:new-dependency-evaluation skill — for a forward-lookingchoice about what to add, not what's already installed: comparing 2-5named candidates ("axios vs got vs node-fetch"), evaluating one candidateagainst its real peers, or shortlisting candidates from a described need.Orchestrates compare_packages/suggest_alternative/search_packagesinto a structured side-by-side with a deterministic pick. Seeskills/new-dependency-evaluation/SKILL.md.
/npmscan:incident-response skill — turns an existing finding, orjust 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. Seeskills/incident-response/SKILL.md.
/npmscan:ci-pr-gate skill — turns a dependency change (abefore/after snapshot, or one or more named "bump X from A to B"upgrades) into one deterministic PASS/WARN/FAIL verdict formatted for aCI check or PR-comment bot, applying a fixed policy on top ofdiff_dependencies/simulate_dependency_upgrade — not a conversationalreport (that's dependency-audit's job). Seeskills/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 atall:

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 aurl 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
├── .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
├── 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

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 apackage.json/name a package and ask) to exercise each skill, and try theprompts in each skill's references/test-prompts.md.

Submitting to a marketplace

NPMScan is already listed in Anthropic's plugin directory (seeOfficial listings). The values used for that submission formare in SUBMISSION.md; update them there when the pluginchanges.

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

See Anthropic's plugin docs forthe 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 andpoints at the same skills/ directory. Claude Code ignores that file, andKimi prefers it over .claude-plugin/plugin.json, so each client reads itsown 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 askPlugin 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: fullzh-CN locale, brandColor (#ef4444, npmscan.com's primary red), a darkrounded-tile icon.png built from the site's dark-mode logo, andhostKind: hosted. Kimi's local validation passed with 0 errors / 0warnings on v3.0.2 (the last version imported into Kimi; see KIMI.md).Official-marketplace publication goes through a Kimi review step — seeKIMI.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 addroot-level commands/, agents/, or hooks/ directories for Kimi, becauseClaude Code auto-loads those too.

Using it with Grok Build

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

Status: submitted to xAI's official marketplace inxai-org/plugin-marketplace#1506as a remote source pinned to commit 5cbf977 (v3.1.2). It's waiting forxAI to approve the CI run and do a code-owner review. The source stays onthis personal-account repo rather than the NPMscan org, so the Claude andChatGPT listings don't have to move.
After merge: install with /marketplace orgrok plugin install npmscan inside Grok Build.
Updating: Grok Build installs the pinned commit only. To ship a newrelease, open a PR to xai-org/plugin-marketplace that bumps the sha ofthe npmscan entry in .grok-plugin/marketplace.json, then runpython3 scripts/generate-plugin-index.py, scripts/validate-catalog.pyand scripts/generate-plugin-index.py --check there. The index scriptfetches 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 fromskills/.

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 repoby its gemini-cli-extension GitHub topic and re-crawls it daily; there'snothing to submit. Check a change withgemini extensions validate . before pushing.

Antigravity CLI users (which replaced Gemini CLI for free and Google AIPro/Ultra accounts) can bring the extension over withagy 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 andno 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-clickinstaller. Cline's marketplace logo isassets/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 theplugin. 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), notfrom the name in .claude-plugin/marketplace.json, so the plugin ID isnpmscan@npmscan-mcp-plugin. Check it with droid mcp list: npmscanshould 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 officialnpmscan app listing(submission artifacts live in the main npmscan apprepo, under mcp/).

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

License

MIT — see LICENSE.

Made by BlockHacks.io — protecting the open sourceecosystem.

NPMScan plugin for Claude Code