Security scanner for Model Context Protocol (MCP) servers.
mcp-scan is an open-source CLI that inspects MCP servers for known security issues. It connects to a server via stdio, fetches its tool/resource/prompt manifest, and runs a battery of checks against the metadata.
Early alpha. Currently ships 6 checks: 2 protocol-level (prompt injection markers, ANSI/control character smuggling) and 4 source-code AST checks (path traversal, shell injection, SSRF sinks, hardcoded secrets). 19 more are planned — see
docs/checks.mdfor the full roadmap. Only stdio transport is implemented; HTTP/SSE is planned.
Built by Velox Labs — an AI security and platform engineering studio.
Protocol-level checks (run against any MCP server, no source access needed):
| Check | Severity | What it detects |
|---|---|---|
| MCPA-001 | Critical | Prompt-injection markers in tool descriptions (imperative verbs, <system> tags, exfiltration phrases) |
| MCPA-002 | High | ANSI escape sequences, C0 control chars, and zero-width characters hiding payloads in tool descriptions |
Source-code AST checks (require --source <path> pointing at the server's Python source):
| Check | Severity | What it detects |
|---|---|---|
| MCPA-010 | Critical | Path traversal in file handlers — open()/read_text() without is_relative_to() containment (resolve() alone is not sufficient) |
| MCPA-012 | Critical | Shell injection — subprocess with shell=True, especially with f-string/format commands |
| MCPA-060 | High | SSRF sinks — HTTP client calls (httpx, requests, urllib) with variable URLs and no host validation guard |
| MCPA-070 | High | Hardcoded secrets — API keys (sk-, ghp_, AKIA, xoxb-, etc.) and high-entropy strings in secret-named variables |
These catch the tool poisoning attacks published by Trail of Bits and Invariant Labs (2025), the EscapeRoute filesystem sandbox bypass (CVE-2025-53109/53110), and the Anthropic Git MCP argument injection (CVE-2025-68144).
See docs/checks.md for the 19 additional checks planned for v0.1 (dependency CVEs, OAuth conformance, SSRF, exfiltration channels, and more).
pip install velox-mcp-scanRequires Python 3.10+.
# Scan a local stdio MCP server
mcp-scan scan --stdio "python3 -m my_mcp_server"
# Output JSON report
mcp-scan scan --stdio "python3 -m my_mcp_server" --format json --output report.json
# Only run critical-severity checks
mcp-scan scan --stdio "python3 -m my_mcp_server" --severity critical
# List registered checks
mcp-scan list-checksThis repo ships with vulnerable-mcp — a deliberately broken MCP server with 5 planted vulnerabilities. The scanner catches all 5 (7 findings total).
# Protocol-level checks only (catches vuln #1)
mcp-scan scan --stdio "python3 -m vulnerable_mcp.server"
# Protocol + source-code checks (catches all 5 vulns)
mcp-scan scan --stdio "python3 -m vulnerable_mcp.server" --source ./vulnerable_mcpA security scanner that silently passes when something goes wrong is worse than no scanner. mcp-scan follows fail-closed principles:
- Introspection failures are surfaced as critical findings, not swallowed. If the server can't respond to
tools/list, you see aCRITICALfinding, not an empty clean report. - Check execution errors cause non-zero exit, even if no findings were produced. In CI, a broken scan is a failed scan.
- All MCP RPC calls have timeouts (default 30s, configurable via
--timeout). A hanging server can't hang the scanner.
- Current — 6 checks (MCPA-001, MCPA-002, MCPA-010, MCPA-012, MCPA-060, MCPA-070), stdio transport, source-code AST scanning (
--source), terminal/JSON/markdown reports, fail-closed error handling, capability-aware introspection. - v0.1 — 25 checks across tool-schema, resource-access, supply-chain, transport, OAuth, SSRF, exfiltration, and configuration categories. See
docs/checks.md. - v0.3 — OAuth 2.1 DCR flow auditing, multi-server config analysis, fuzz mode.
MIT. See LICENSE.
Found a security issue in mcp-scan itself? Email security@veloxlabs.dev — please do not file a public issue.
