NPMScan MCP Server for ChatGPT
By SHYNGYS SHYNBOLATOV
Overview
Look up npm package metadata, known vulnerabilities, and CVE details directly from a conversation. NPMScan's MCP server gives AI agents read-only tools backed by the npm registry, OSV.dev, GitHub Security Advisories, GitHub's own API, and the NIST National Vulnerability Database: search packages by name or keyword with download counts, dependent-package counts, and typosquat detection on every result; inspect a package's install scripts, maintainers, license, GitHub stars, and download trend before installing, or compare 2-5 candidates side-by-side with a deterministic pick; check an exact version pinned in a lockfile, or simulate upgrading one before running npm install to see if it's a safe patch or a likely-breaking major bump; query vulnerabilities for one package or up to 100 at once, each finding enriched with severity, a summary, CVE aliases, and the fixed version rather than a bare advisory ID; audit an entire GitHub repository's dependencies (including monorepo workspaces) in one call, or generate a spec-valid CycloneDX/SPDX SBOM with vulnerability and license data embedded; rank the findings from a raw npm audit --json report by CISA KEV/FIRST EPSS exploitation data to know what to fix first, then pull the concrete, ordered remediation playbook for a flagged finding; check an npm maintainer account's publish history for a compromised-account-style cluster, or pull their basic profile; browse the latest npm advisories from either GitHub's curated, mostly CVE-backed reviewed set or its known-malicious-package malware feed, filterable by severity, vulnerability category (XSS, SQL/NoSQL Injection, SSRF, Access Control, Code Injection, and 15 more, reviewed only), affected package, or an exact GHSA/CVE ID; and look up authoritative CVSS/CWE data for any CVE across any ecosystem, enriched with CISA's Known Exploited Vulnerabilities status and FIRST.org's EPSS exploitation-probability score. No API key or authentication is required, and every result links back to the full write-up on npmscan.com.
How to connect
- ChatGPT: Open the NPMScan listing in the ChatGPT app directory and choose Connect. ChatGPT listing NPMScan exposes 23 tools here.
Tools
analyze_transitive_dependencies
ChatGPTmaxDepth levels (default 2, max 3) and check every resolved package@version against OSV.dev, so vulnerabilities several levels down still surface. Read summary first; vulnerablePaths answers "which of my dependencies pulled this in"; nodes has the full graph. npm aliases are followed (actualName). Before calling a result clean: - A node with resolutionError (unsatisfiable range, 404, or a git/file/workspace/URL specifier) has isVulnerable: null — it was never scanned, not clean. - Only "dependencies" are followed (not dev/peer/optional). Each range is resolved independently to its max-satisfying version, so this shows which vulnerable versions are reachable, not npm's exact hoisted install. - The walk has a node budget: check truncated/truncationNote. Use batch_query_vulnerabilities instead when you already have a flat list of exact versions (faster, no graph walk).audit_github_repository
ChatGPTref), and detects monorepos (package.json workspaces, pnpm-workspace.yaml), merging member dependencies (up to 50 members). What it checks: - Every lockfile entry (up to 3,000; the repo's own workspace/link entries skipped) against OSV.dev, so vulnerablePackageCount covers the whole dependency set. - Up to 100 packages, vulnerable ones first, also get a license verdict (same default policy as check_license_compliance, or pass policy) and an install-script signal; up to 10 with lifecycle scripts get the deep tarball scan (installScriptScanScope). - Up to 5 high-risk packages (critical/high vulnerability, possible typosquat, deprecated) get the maintainer-change and provenance checks; others are named in ownershipCheckNote. Read coverage and the summary before calling a repo clean: a summary starting PARTIAL AUDIT (coverage.complete: false) means not every package got every check. findings has full detail only for packages with something to report; the other detailed packages are listed compactly in cleanFindings. Vulnerable packages past the 100-package detail cap are in overflowVulnerablePackages. peerDependencies are skipped unless includePeerDependencies: true. This is the most expensive tool here — do not call it in a loop across many repos.batch_query_vulnerabilities
ChatGPTpackages: [{name, version?}], or raw package.json / package-lock / yarn.lock / pnpm-lock / CycloneDX / SPDX content via content. Large inventories are chunked automatically. Each finding has severity, summary, CVE aliases, fixedVersion and isMalware, so no per-package follow-up is needed. Before calling anything clean, read: - unresolvedPackages/nonexistentVersions (and each result's registryStatus): a name or version not on npm shows vulnerabilityCount 0 just like a clean package. A version npm removed can still have real OSV findings (often malware). - A packages entry with no version is checked against every historical version; confirm against the version actually in use before calling it vulnerable. - signals (deprecated, hasInstallScripts, popularity/maintenance tiers, possibleTyposquatOf): 0 vulnerabilities can still be deprecated, abandoned or a typosquat. signals is null for git/file/workspace/URL entries, which are not scanned. - source (lockfile input): nonRegistryHost means the tarball comes from an unexpected host; identityMismatch means it is a different package/version than declared (resolvedName/resolvedVersion) and the counts describe the declared one. Treat both as lockfile tampering. - Use uniqueVulnerabilityCount for distinct issues; raw counts can list one CVE twice. - package.json input: projectLifecycleScripts/projectLifecycleScriptRisk are the project's own install scripts; peerDependencies are skipped unless includePeerDependencies: true (see ignoredPeerDependencyNames); declaredSpec marks a version resolved from a range, which can change on the next install. - npm aliases are followed: package.actualName is the real package the data describes.check_license_compliance
ChatGPTpolicy.deny entries always win over policy.allow (so a name can appear in both without a silent contradiction); with policy.allow set, anything not matching it is a violation (unproven is treated as non-compliant); with neither given, the default policy flags only copyleft/network-copyleft/proprietary (e.g. GPL/AGPL/UNLICENSED) — weak-copyleft (LGPL/MPL/EPL) and unrecognized license strings are surfaced but not auto-flagged. Policy entries accept an exact SPDX id, a family prefix ("GPL" catches GPL-2.0/GPL-3.0-only/etc.), or a category name. This reads only the registry-declared license field — it does not fetch or parse LICENSE file contents from the source repository.check_maintainer_blast_radius
ChatGPTcheck_maintainer_changes
ChatGPTnpm publish). Use it for the 'who controls this package, and did that change recently' question; use get_package/check_package_provenance for general health and publish integrity. Flags: 1. a maintainer added recently who then published soon after, on a package with real prior history — the takeover shape behind ua-parser-js, event-stream and the 2025 chalk/debug ('qix') compromise 2. the whole maintainer list replaced at once 3. a long-standing maintainer quietly dropped 4. a maintainer change on npm AFTER the latest release — more urgent: access changed hands but nothing has shipped yet It also checks the declared GitHub repository: transferred or renamed (repository.ownerLogin/ownerAvatarUrl show the CURRENT owner), unreachable, or a latest release that landed long after any real push activity. If it flags a newly added or fully replaced maintainer, follow up with check_maintainer_blast_radius on that username to see whether the same account touched other packages at the same time. Findings are signals to verify, not proof of compromise.check_package_provenance
ChatGPTnpm publish --provenance), and cross-checks that provenance against reality rather than just reporting its presence. Three checks: (1) parses the SLSA build attestation (declared source repo, commit, builder identity, GitHub Actions run URL) and flags a builder that isn't GitHub-hosted, or an attested source repo that doesn't match package.json's own repository field; (2) when this version LACKS provenance, checks whether most peer packages (same npm scope, or same maintainer for an unscoped name) DO have it — a package that's the odd one out in an org that otherwise always publishes from CI is a real anomaly, not proof of malice; (3) fetches package.json from the source repository at the exact attested commit (or a best-effort matching git tag when no provenance/commit is available) and diffs its install-lifecycle scripts (preinstall/install/postinstall/prepare) and dependency names against what's actually in the published tarball — this is the single highest-signal check here, since a script or dependency that exists on npm but was never committed is exactly the pattern of a stolen-npm-token publish that bypasses CI (the event-stream/ua-parser-js incident shape). This is a heuristic, structural check: it does NOT cryptographically re-verify the Sigstore bundle (Fulcio cert chain, Rekor inclusion proof) — it trusts that npm's registry already refused to accept a publish that failed that verification, and checks the CONTENT of what the registry reports instead. Most packages don't use --provenance yet, so its bare absence is never scored on its own — only an org-norm anomaly or an actual source mismatch is. Use get_package/get_package_version first for basic package info; use this specifically to assess publish-integrity risk.compare_packages
ChatGPTtruncated/sizeUnknownCount mark a partial sum). differentiators names who stands out on each dimension. recommendation.pick comes from a weighted score (popularity, maintenance, deprecation, vulnerabilities, typosquat flag, install-script risk, TypeScript, stars; size is reported, not scored) — never a deprecated or typosquat-flagged candidate — with a rationale and a confidence from how close the top two scored. Before trusting the result: vulnerabilityCheckFailed: true means the safe/not-safe answer is unknown, not clean; a name that cannot be resolved stays in candidates with found: false and resolutionError.diff_dependencies
ChatGPTactualName). Up to 100 added/changed packages are checked in detail. Ideal for a CI gate. Per added/changed package: - installScriptIntroduced: a preinstall/install/postinstall script the old version lacked — the shape of a compromised-maintainer release. prepare never runs on a registry install, so it is excluded; installScriptKeysIntroduced lists every new key, prepare included. - sourceIntegrityChanged: the same version now resolves to a different tarball URL or hash, or a bump moved to another host (ordinary bumps are not flagged). A same-version swap is changeType: "source-swap". - identityMismatch: the tarball is a different package or version than declared; tarballName/tarballVersion say what really installs, and the vulnerability fields describe that. - vulnerabilityDelta (introduced/fixed/still-vulnerable/still-clean) plus the findings, each with isMalware. Project-level: projectLifecycleChanges diffs the project's own root install scripts (package.json only; a PR that only adds a root postinstall changes no dependency), and overridesChanges diffs overrides/resolutions/pnpm.overrides, from package.json or between two pnpm-lock.yaml files (removing one can let a vulnerable version back in). Both count toward flaggedCount. Read comparisonNote when the two snapshots differ in format. Install-script checks are presence-only; use analyze_install_script to see what a script does.enrich_npm_audit
ChatGPTnpm audit --json (npm 7+'s {vulnerabilities: {...}} format, or legacy npm 6's {advisories: {...}}), parses it directly — no need to re-paste package.json/lockfile content — and runs it through the same remove-now/patch-now/patch-soon/scheduled/monitor ranking prioritize_remediation exposes for hand-built finding lists (an advisory that is malware — a MAL- id, or a GHSA whose OSV record carries CWE-506 / a MAL- alias — is auto-detected and forces remove-now). npm audit's JSON almost never includes a CVE id (only a GHSA advisory URL), so this resolves each GHSA to its CVE alias via OSV.dev when one exists (ghsaResolvedToCveCount reports how many) before doing the same CISA KEV + FIRST.org EPSS + severity scoring — skipping this step would silently degrade most findings to severity-only ranking despite prioritize_remediation being built around CVE-keyed KEV/EPSS data. Also carries through npm-audit-specific context prioritize_remediation itself has no field for: isDirect (direct vs. transitive dependency) and fixAvailable/fixTarget (npm's own computed fix — note fixTarget can name a different package than the vulnerable one, e.g. bumping a parent to pull in a patched transitive dependency). A package with more than one distinct advisory in the source report only has its first advisory used for ranking; a warning names the package so query_vulnerabilities can be called on it directly for the rest. yarn audit --json and pnpm audit --json use different report shapes and are not supported — use batch_query_vulnerabilities with the project's manifest/lockfile for those instead.generate_sbom
ChatGPTcontent — emits a spec-valid CycloneDX 1.6 or SPDX 2.3 JSON document (pick with format, default 'cyclonedx') with npmscan's own OSV.dev vulnerability findings and registry license data embedded in each spec's native fields: CycloneDX gets a top-level vulnerabilities[] array (VEX analysis.state: 'in_triage' — an unreviewed automated finding, not a claim of exploitability) and per-component licenses[]; SPDX (which has no vulnerabilities array in 2.3) gets one externalRefs SECURITY/advisory entry per finding and licenseDeclared/licenseConcluded. Only a flat package inventory is known here, so the CycloneDX dependencies[] transitive graph and any SPDX package hierarchy are intentionally omitted rather than fabricated. Set includeVulnerabilities/includeLicenses to false to skip either enrichment pass (faster, no registry/OSV calls for that pass); pass policy (same shape as check_license_compliance) to also get per-package compliance context; componentName/componentVersion name the SBOM's own root component/document if known. When content is a package.json, peerDependencies are excluded by default (a peer is often intentionally left unresolved by the consumer) — pass includePeerDependencies: true to include them as SBOM components too, since an SBOM meant to be complete shouldn't silently omit a whole dependency category.get_cve
ChatGPTkev, non-null only if this CVE is a confirmed, actively-exploited-in-the-wild vulnerability — treat that as an urgent-patch signal regardless of CVSS score) and FIRST.org EPSS (epss, the probability of exploitation in the next 30 days — a better prioritization signal than CVSS severity alone, which measures impact, not likelihood). If the KEV or EPSS lookup itself fails (network/timeout/upstream outage), kev/epss come back null only because those fields have to be nullable — kevCheckFailed/epssCheckFailed (true in that case) is the real signal, and means "unknown", not "confirmed absent/unscored". For a search, a failed EPSS batch call sets epssCheckFailed on every result in that response, since one call scores every id together; kevCheckFailed is tracked per-CVE since each is looked up independently. For a single cveId lookup, if NVD has no record yet or hasn't scored it, this falls back to the raw MITRE CVE record automatically (source: "mitre" on the result) rather than returning nothing. NVD is NOT npm-scoped — unlike query_vulnerabilities/get_latest_advisories, search results can include CVEs for any ecosystem, so pass keywordSearch (e.g. the package name) to narrow it. Prefer this for the authoritative CVSS score/vector/KEV/EPSS data on a CVE already found via another tool, or when a user pastes a CVE ID/link directly; prefer get_latest_advisories for npm-specific browsing. NVD enforces a strict shared rate limit, so this tool may occasionally ask you to retry in a few seconds — do so rather than assuming failure.get_latest_advisories
ChatGPTget_maintainer_profile
ChatGPTget_package
ChatGPTfalse only because the field has to be a boolean — vulnerabilityCheckFailed:true is the real signal there, and means the safe/not-safe answer is unknown, not confirmed clean. Also returns popularityTier/maintenanceTier (deterministic rule-based labels, not model-generated) and a plain-language maintenanceSummary, plus a possibleTyposquatOf flag if the name is one typo away from a top-5,000 package while itself being obscure — read deprecated and maintenanceSummary before recommending a package, since a long gap since the last release can mean either a stable/finished package or a slowing one. Includes a link to the full npmscan.com analysis page.get_package_version
ChatGPTfalse only because the field has to be a boolean — vulnerabilityCheckFailed:true is the real signal there, and means the answer is unknown, not confirmed clean.get_remediation_playbook
ChatGPTrule value from analyze_install_script, check_maintainer_changes, or check_package_provenance to the matching human-authored incident-response playbook (the same content published at /docs/playbooks) and returns its concrete, ordered steps, severity tier, real-incident references, and prevention tips — not just a link. Pass the exact rule string(s) a prior finding already returned (batch up to 10 in one call to cover a whole findings array; duplicates resolving to the same playbook are deduplicated) or an id to look up a specific playbook by slug directly. Each matched rule also gets its own short situationNote explaining specifically what that rule caught — so a batch of several different rules landing on the same playbook does not read as identical, repeated boilerplate. An unrecognized rule or id is not an error — it comes back with matched:false and a note, since a low-severity or baseline-only finding (e.g. analyze_install_script's lifecycle-present) legitimately has no dedicated playbook.prioritize_remediation
ChatGPT{packageName, cveId?, severity?, advisoryId?, currentVersion?, fixedVersion?, findingType?}. Each gets a tier: remove-now / patch-now / patch-soon / scheduled / monitor. How the tier is decided: - remove-now: confirmed malware — findingType: "malware", a MAL- advisoryId, or an advisoryId whose OSV record is a malware advisory (CWE-506 or a MAL- alias, looked up automatically). Malware is removed, not patched. Advisories that could not be looked up are listed in malwareCheckFailedAdvisoryIds. - patch-now: on the CISA KEV list (actively exploited), whatever the severity. - otherwise a score led by FIRST.org EPSS (30-day exploitation probability), with severity as a secondary signal — or the only signal when there is no EPSS data (no CVE id). An EPSS of 10% or more always ranks at least patch-soon. The tier is a fix-ORDER across a backlog, not a severity verdict or a merge gate: a CRITICAL CVE with low EPSS can rank monitor. Never describe a monitor/scheduled finding as "low severity", and judge whether a change that INTRODUCES a vulnerability is acceptable by its severity, not this tier.query_vulnerabilities
ChatGPTsearch_packages
ChatGPTsimulate_dependency_upgrade
ChatGPTpackageName + currentVersion + targetVersion (omit target for "latest"), or packages: [...] (1-100) to check many in one call; a name that cannot be resolved comes back with fetchError instead of failing the batch. A natural follow-up to prioritize_remediation: pass its packageName/currentVersion/fixedVersion straight in. What it checks: - semver jump (major/minor/patch/prerelease; a 0.x minor bump counts as breaking; skipped majors are flagged) - registry signals on the target: deprecated, a newly added preinstall/install/postinstall script (installScriptIntroduced; a new prepare is listed in installScriptKeysIntroduced but never runs on a registry install), a tightened engines.node, prerelease - OSV for both versions: vulnerabilityDelta (introduced/fixed/still-vulnerable/still-clean) and targetVulnerabilities with isMalware — catching a "fix" that does not clear every CVE Result: one riskTier — safe / low-risk / review-recommended / breaking-change-likely / unknown / do-not-upgrade — with reasons. do-not-upgrade means the target is known malware, or npm no longer lists it while OSV still has advisories for it (how npm removes malicious releases). It does not read changelogs or diff source; it is a fast pre-check, not a substitute for release notes on a major bump.suggest_alternative
ChatGPTfalse only because the field has to be a boolean — source.vulnerabilityCheckFailed:true is the real signal there, and means that safe/not-safe answer is unknown, not confirmed clean.Example Prompts
Click any prompt to copy it.
Links
Similar Apps
Listed on MCP App Store
Add this badge to your site or README. It links to this page.
HTML
<a href="https://mcp-app-store.keenethics-labs.com/app/npmscan"><img src="https://mcp-app-store.keenethics-labs.com/badges/listed-on-mcp-app-store.svg" alt="Listed on MCP App Store" width="220" height="44"></a>
Markdown
[](https://mcp-app-store.keenethics-labs.com/app/npmscan)






