mcpscan — MCP server & agent-skill supply-chain scanner (MVP)

Supply-chain security scanner for MCP servers and agent skills (Claude, Cursor, VS Code, Windsurf).

Quickstart

Install (Node.js ≥ 18):

npm install -g mcpscan   # or: npx mcpscan scan

Claude Code

claude mcp add mcpscan -- npx -y mcpscan@0.1.0 mcp

Cursor — add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). The same snippet works for Claude Desktop, VS Code and Windsurf:

{ "mcpServers": { "mcpscan": { "command": "npx", "args": ["-y", "mcpscan@0.1.0", "mcp"] } } }

Restart the client and the tools appear. Full details below.

Teams install third-party MCP servers and agent skills (Claude Code skills, plugin skills, Cursor skills) the same way they once installed random npm packages: copy a JSON snippet, run npx -y something, and trust it. Those components can be dead, over-privileged, or can hide prompt injection in a SKILL.md or a tool description.

mcpscan is a zero-dependency Node.js CLI that finds every MCP config and skill folder on a machine (Windows, macOS, Linux), runs offline static checks, and writes text / JSON / SARIF / HTML reports with CI-friendly exit codes. It can also run as a read-only MCP server so an agent can audit its own environment.

Status: MVP. Static, pattern-based analysis. Read Limitations before relying on it.

Related MCP server: owasp-mcp-scan

What it finds

mcpscan rules prints the catalog.

Where it looks

Run mcpscan paths to see the exact paths checked on your OS. JSONC (comments, trailing commas) is supported. Symlinks are never followed.

Install & use

Needs Node.js 18 or newer. No runtime dependencies, so you don't have to run npm install to use it.

Windows (PowerShell)

# from the folder you copied (e.g. C:\path\to\mcpscan)
cd $env:USERPROFILE\mcp-skill-scanner
node .\bin\mcpscan.js paths                       # where it will look
node .\bin\mcpscan.js scan                        # user configs + current folder
node .\bin\mcpscan.js scan -p C:\code\my-repo -f html -o "$env:TEMP\mcpscan.html"
Start-Process "$env:TEMP\mcpscan.html"
npm test                                          # run the test suite (offline)

# optional: put `mcpscan` on PATH
npm link
mcpscan scan --fail-on critical
$LASTEXITCODE                                     # 0 = clean, 1 = findings, 2 = error

If PowerShell blocks the mcpscan.ps1 shim that npm link creates, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, or keep calling node .\bin\mcpscan.js.

macOS / Linux

node bin/mcpscan.js scan
node bin/mcpscan.js scan -p ~/code/app -f sarif -o mcpscan.sarif

Options

mcpscan [scan] [-p dir]... [-c config.json]... [-s skillsDir]... [-t tools.json]...
        [-f text|json|sarif|html] [-o file] [--fail-on critical|high|medium|low|info|none]
        [--min-severity sev] [--policy file] [--online] [--root home] [--platform win32|darwin|linux]
        [--no-default-roots] [--no-color]
mcpscan list | paths | rules | init-policy | mcp

• Vet a skill before installing: mcpscan scan --no-default-roots -s .\downloaded-skill

• Vet tool descriptions: save a server's tools/list result to JSON, then mcpscan scan --no-default-roots -t tools.json

• Exit codes: 0 = nothing at or above --fail-on (default high, or failOn from the policy), 1 = findings, 2 = usage/runtime error.

CI (GitHub Actions + code scanning)

- run: node bin/mcpscan.js scan --no-default-roots -p . -f sarif -o mcpscan.sarif --fail-on high
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with: { sarif_file: mcpscan.sarif }

Policy file (mcpscan.policy.json)

Loaded from the current directory, or pass --policy path. mcpscan init-policy writes a starter file.

{
  "version": 1,
  "failOn": "high",
  "requireAllowList": false,
  "allow": { "servers": [], "packages": ["@modelcontextprotocol/*"], "hosts": ["mcp.linear.app"], "skills": [] },
  "deny":  { "servers": [], "packages": ["*-mcp-free-*"], "hosts": ["*.ngrok-free.app"], "skills": [] },
  "ignore": [ { "rule": "MCP018" }, { "rule": "MCP008", "target": "internal-*" } ],
  "severityOverrides": { "MCP014": "low" }
}

* is a wildcard. When requireAllowList is true, any server or skill that isn't allow-listed raises MCP012.

MCP server mode (read-only)

mcpscan mcp runs a stdio MCP server (JSON-RPC 2.0, protocol 2025-06-18) with four tools, each annotated readOnlyHint: true: scan_all, list_discovered, scan_skill, scan_text. None of them writes files or touches the network.

{ "mcpServers": { "mcpscan": { "command": "node", "args": ["C:\\path\\to\\mcpscan\\bin\\mcpscan.js", "mcp"] } } }

Claude Code: claude mcp add mcpscan -- node /path/to/mcpscan/bin/mcpscan.js mcp

Claude Code skill

skills/mcpscan/ holds a ready-made skill (SKILL.md + reference.md). Copy the folder into %USERPROFILE%\.claude\skills\ (Windows) or ~/.claude/skills/ (macOS/Linux), or into a repo's .claude/skills/:

Copy-Item -Recurse .\skills\mcpscan "$env:USERPROFILE\.claude\skills\mcpscan"

Competitors and prior art

• mcp-scan / Snyk Agent Scan by Invariant Labs, acquired by Snyk on June 24, 2025. It discovers MCP servers and skills and scans tool descriptions for tool poisoning, rug pulls, and cross-origin escalation. It connects to servers and sends tool names and descriptions to a remote analysis API. Snyk also offers a background mode that reports to Snyk Evo for company-wide monitoring.

  • Repo: https://github.com/invariantlabs-ai/mcp-scan

  • Launch post: https://invariantlabs.ai/blog/introducing-mcp-scan

  • Acquisition: https://snyk.io/news/snyk-acquires-invariant-labs-to-accelerate-agentic-ai-security-innovation/

• Cisco AI Defense mcp-scanner, which scans MCP servers for threats: https://github.com/cisco-ai-defense/mcp-scanner

How mcpscan differs: it runs fully offline by default and sends no tool descriptions to a third party. It has zero dependencies, so it's easy to audit. It covers supply-chain hygiene (pinning, secrets, filesystem scope, transport, liveness) as well as injection. It produces native SARIF for CI, applies a simple policy file, and covers Windows paths explicitly. Its trade-off: no LLM-based semantic analysis, and it doesn't connect to live servers.

Limitations

• Detection is regex/heuristic. Expect false positives. Skills that legitimately say "do not tell the user X" get flagged MCP001. Expect false negatives too: paraphrased or translated injections, payloads split across files, and obfuscation beyond base64 and hidden Unicode get through.

• Tool descriptions are only checked when they appear in a config, or when you pass a tools/list dump with -t. mcpscan doesn't launch or connect to servers, so it can't detect rug pulls (description changes over time).

• --online checks npm and GitHub only. PyPI and Docker Hub liveness aren't implemented, and unauthenticated GitHub API calls are rate-limited (60 requests/hour).

• Config paths cover the clients' current documented defaults. Portable installs, custom CLAUDE_CONFIG_DIR, and enterprise-managed settings aren't discovered automatically; pass them with -c/-s.

• Homoglyph and confusable-character detection isn't implemented.

• The MCP server mode implements tools only (no resources or prompts) over stdio.

Development

npm run build   # syntax-check all files, load modules, validate policy JSON
npm test        # node:test, fully offline (fetch is stubbed to throw)
npm run demo    # scan the bundled malicious fixtures
node scripts/make-fixtures.js   # regenerate fixtures (all secrets are fake)

License

MIT © 2026 Kurt Francisco. See LICENSE.

Contributing

Issues and pull requests are welcome at https://github.com/fpavia111-creator/mcpscan. See CONTRIBUTING.md.