MCP Security Scanner: Tool Poisoning, Secrets, Rug Pull Checks

Scan MCP servers and MCP client configs for tool poisoning, tool shadowing, hidden Unicode, rug pulls, plaintext secrets and risky launch commands, offline: nothing is sent to any API. Python 3.9+, standard library only, one folder.

python3 tools/mcpscan.py config                                   # every MCP config found on this machine
python3 tools/mcpscan.py server -- npx -y @acme/mcp-server@1.4.2  # one stdio server: list its tools, scan them
python3 tools/mcpscan.py server --url https://mcp.example.com/mcp --header "Authorization: Bearer $TOKEN"
python3 tools/mcpscan.py servers .cursor/mcp.json                 # start every server in a config, scan them together
python3 tools/mcpscan.py pin -- <server command>                  # fingerprint every tool definition (mcp-pins.json)
python3 tools/mcpscan.py verify -- <server command>               # later: what changed since you pinned it?
python3 tools/mcpscan.py rules                                    # all 27 rules

--json for scripts, --sarif out.sarif for GitHub code scanning, --fail-on high|medium|low|none (default high), --ignore MCP-T13,MCP-C10 to skip rules. Exit code 0 = clean at that level, 1 = findings, 2 = could not read or reach it. ./tools/demo.sh runs everything below on the bundled examples.

Tool definitions (names, descriptions, titles, every parameter description and default, server instructions), fetched over stdio or Streamable HTTP from MCP 2026-07-28 or 2025-11-25 servers:

Client configs: Cursor (.cursor/mcp.json, ~/.cursor/mcp.json), Claude Desktop (macOS, Windows, Linux), Claude Code (.mcp.json, ~/.claude.json incl. per-project servers), VS Code (.vscode/mcp.json and user mcp.json, comments allowed), Windsurf, Gemini CLI (settings.json), Codex (config.toml), Cline and Roo:

Rug pulls: pin stores a SHA-256 of each tool's name, description, schemas and annotations in mcp-pins.json (commit it). verify reports changed tools with a diff of the description (MCP-R01, high), new tools (R02) and removed tools (R03), then runs the normal scan on the new definitions.

ci/mcp-security.yml is a GitHub Actions workflow that scans the repo's MCP config and your own server against the committed pins, and uploads SARIF so findings show up in the Security tab and on pull requests.

• examples/poisoned_server.py: a harmless server that reproduces publicly documented attacks (the poisoned add tool that asks for ~/.cursor/mcp.json in a sidenote, send_email shadowing hidden in Unicode tag characters, pressure framing, wrong annotations, a shell tool, and a rug pull with RUG=1). 12 findings.
• examples/clean_server.py and examples/email_server.py: honest servers. 0 findings.
• examples/benign_tools.json: 25 everyday tool definitions (files, GitHub, browser, SQL, docs, Slack, calendar): 0 high or medium findings, used as a false-positive check.
• examples/configs/: a risky Cursor config (13 findings), a clean one (0), a VS Code JSONC file, a Codex TOML file and a two-server config for cross-server checks.

./run_tests.sh (18 tests, Python 3.13 and 3.10): every attack in the poisoned server, zero findings on the clean servers and the benign corpus, cross-server duplicates, every config rule on the risky config with secrets masked in the output, JSONC and TOML parsing (including the Python 3.9/3.10 TOML fallback), pin/verify catching a changed description, SARIF 2.1.0 output, --ignore, and exit codes. We also ran it on two of our own MCP servers (SQLite and Obsidian): 0 findings.

• Pattern rules catch known techniques, not every possible injection. Reworded or translated attacks can slip through, and a clean scan does not prove a server is safe. Pinning plus review is the strongest protection here.
• It reads tool definitions, not server code: a server with clean descriptions can still do harm when a tool runs.
• Prompts and resources are not scanned yet; tools and server instructions are.
• config and servers mode start or read what is on your machine; servers mode launches every server in the file, so run it only on configs you would start anyway.
• OAuth flows are not handled: pass a token with --header.