mcp-recon

Reconnaissance and known-issue scanner for Model Context Protocol (MCP) servers. Think of it as nmap for MCP: it fingerprints what's there and flags behavior patterns associated with publicly disclosed vulnerability classes. It does not declare a server "safe" or "unsafe" - it reports observations, and the operator interprets them in context.

Use with authorization only

Only run mcp-recon against servers you own or have explicit permission to test. Unauthorized scanning may violate computer misuse laws in your jurisdiction. The tool is rate-limited by default and refuses to send state-mutating calls, but responsibility for scope is on the operator.

Install

pipx install mcp-recon
# or
pip install --user mcp-recon

Python 3.10+ required.

Quick start

# Scan an HTTP MCP endpoint
mcp-recon scan https://example.com/api/mcp

# Scan a stdio MCP server (spawn as subprocess, JSON-RPC over stdin/stdout)
mcp-recon scan --stdio "mcp-server-fetch"
mcp-recon scan --stdio "node /path/to/memory-server/dist/index.js /tmp/mem.json"
mcp-recon scan --stdio "uvx mcp-server-time"

# JSON output for automation
mcp-recon scan https://example.com/api/mcp --output json

# Markdown output for dropping into bug-bounty reports
mcp-recon scan https://example.com/api/mcp --output markdown

# Scope-binding probe on an OAuth-gated server
MCP_RECON_TOKEN=<access-token> mcp-recon scan https://example.com/api/mcp

# Route requests through Burp / mitmproxy (HTTP mode only)
mcp-recon scan https://example.com/api/mcp --proxy http://127.0.0.1:8080

When --stdio is set, the five HTTP-specific checks (transport-hygiene, cors-policy, auth-header-hygiene, discovery-consistency, scope-binding) are marked skipped-not-applicable. The remaining five checks (fingerprint, error-verbosity, tool-description-anomalies, multi-request-pattern, undocumented-capabilities) run over the stdio transport.

Exit codes:

What it checks

Ten checks, all generic. Each describes what it observed rather than declaring a verdict.

Each flagged observation ships with:

• A plain-English summary of what was observed.
• The concrete evidence the tool captured.
• A suggested manual follow-up command.
• Links to public CVEs or writeups that exemplify the class.

Artifacts

Every scan writes a directory of raw JSON artifacts to ./mcp-recon-artifacts/<target>_<timestamp>/:

report.json        structured result (schema-versioned)
exchanges.json     every HTTP request / response pair, with Authorization / Cookie headers redacted

Artifact directory is chmod 700. Individual files are chmod 600. Secrets are redacted by default; pass --include-secrets to disable redaction (use only when you need raw evidence for a report and understand the risk).

Honest limits

• A clean scan does not mean a server is secure. The tool checks a finite set of known-issue patterns.
• Observations are not vulnerabilities. They're signals that match classes of previously disclosed bugs. Always validate manually before reporting.
• The tool is read-only at the MCP protocol layer. It never calls state-changing tools like update_cart or equivalents.
• Rate limiting is on by default (100ms between requests). Use --aggressive only against infrastructure you own.

License

MIT. See LICENSE.

Author

Jashid Sany - jashidsany.com - @jashidsany on GitHub

Related research:

• Zomato MCP OAuth scope not enforced
• mcp-server-fetch DNS rebinding (GHSA in flight)
• Claude Code MCP trust-model findings at jashidsany.com/security-research/ai-security/