Pkgxray

What the pkgxray MCP server does

The pkgxray MCP server makes pkgxray's auditing functions available through MCP so an agent can use the same checks that are available from the command line. The project is designed to inspect software before installation, package promotion, or connection to an MCP server. It covers npm and PyPI packages, GitHub repositories, local directories, dependency lockfiles, MCP servers, and AI-agent extensions.

Results use three policy-oriented decisions. SAFE means no high- or medium-risk indicators were found and has exit code 0. REVIEW indicates incomplete evidence or a privileged capability requiring human inspection and has exit code 3. BLOCK indicates high-severity cited evidence and has exit code 2. Findings identify the relevant file and evidence rather than returning an unexplained score.

How it works

Normal scans stage package archives in quarantine and read them as bytes. Package code, lifecycle scripts, and install hooks are not executed during these scans. The verdict comes from fixed detection rules rather than a language model, so text inside a package cannot alter the decision logic.

Checks include credential and secret-store access, cloud metadata harvesting, prompt injection, Unicode smuggling, encoded payloads, stage-two loaders, exfiltration, persistence, CI/CD workflow injection, self-deleting droppers, registry replication, install-time execution, obfuscated command arguments, unpublished lockfile names, known CVEs, npm-to-GitHub artifact differences, trojaned updates, and suspicious MCP capability surfaces.

The guard command vets an individual target, audit examines supported dependency files, and recheck compares dependencies over time for regressions. The mcp command can gate an MCP server before connection and supports rechecking for changes. A runtime proxy mode can inspect each live MCP tool call, but that is a separate execution surface from ordinary static scanning.

Setup and configuration

The package is published on npm. The README demonstrates running a scan without first installing pkgxray locally:

npx --yes pkgxray@1.0.5 guard npm:express@4.21.0

For MCP use, the pkgxray MCP server is documented as an MCP-client integration, but the supplied material does not include its exact launch command or client configuration block. A .pkgxray.json file can tune policy across entry points; when no configuration is present, the strictest settings apply. Configuration cannot suppress a CVE, and a scan error fails closed to REVIEW.

Tools and capabilities

The pkgxray MCP server is suited to exposing audit operations to coding agents and MCP clients. The underlying command-line surfaces support:

• Pre-install checks for npm and PyPI packages.
• Scans of GitHub repositories and local directories.
• Audits for npm and Python dependency manifests and lockfiles.
• Pre-connection checks for MCP servers.
• Scheduled dependency rechecks for upgrade regressions.
• JSON or Markdown output for automation and human review.
• CI-friendly decisions based on stable exit codes.

The project also documents integrations with Cursor, Windsurf, Codex, Claude Code, GitHub Actions, Hookshot, and MCP clients. These are documented setup targets, not claims of vendor endorsement.

Limitations and notes

A SAFE result is not proof that a package is harmless. Static analysis may miss a payload downloaded only after execution. The optional canary mode executes a package in a sandbox to confirm behavior, but it cannot prove that a package is safe. Listing an MCP server's tools, using the runtime proxy, and running the canary have different execution boundaries from normal guard and audit scans.

The pkgxray MCP server does not replace CVE-focused tools such as npm audit or OSV-Scanner; the README recommends running those alongside pkgxray. The supplied material also does not specify an MCP transport, authentication mechanism, or exact tool names exposed by the MCP interface.