mcpsec 0.4.0

Security scanner for MCP (Model Context Protocol) server implementations

⚡ mcpsec

Security scanner for MCP (Model Context Protocol) server implementations.

MCP is the universal protocol connecting AI agents (Claude, ChatGPT, Gemini, Cursor) to external tools and data sources. It's adopted by every major AI company — Anthropic, OpenAI, Google, Microsoft. Its security is broken. mcpsec finds the vulnerabilities.

  ███╗   ███╗ ██████╗██████╗ ███████╗███████╗ ██████╗
  ████╗ ████║██╔════╝██╔══██╗██╔════╝██╔════╝██╔════╝
  ██╔████╔██║██║     ██████╔╝███████╗█████╗  ██║     
  ██║╚██╔╝██║██║     ██╔═══╝ ╚════██║██╔══╝  ██║     
  ██║ ╚═╝ ██║╚██████╗██║     ███████║███████╗╚██████╗
  ╚═╝     ╚═╝ ╚═════╝╚═╝     ╚══════╝╚══════╝ ╚═════╝

Why?

• 82% of MCP implementations have path traversal vulnerabilities (Endor Labs)
• 67% are vulnerable to code injection
• ~2,000 internet-exposed MCP servers found with zero authentication (Knostic)
• Anthropic's own Git MCP server had 3 critical RCE vulnerabilities (CVE-2025-68143/44/45)
• Nobody built an open-source scanner for this. Until now.

Install

pip install mcpsec

Or install from source:

git clone https://github.com/manthanghasadiya/mcpsec.git
cd mcpsec
pip install -e .

Quick Start

# Scan an MCP server running via stdio
mcpsec scan --stdio "npx @modelcontextprotocol/server-filesystem /tmp"

# 🧠 Run AI-Powered Scan (Generates payloads + Validates findings)
# Requires DEEPSEEK_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY
mcpsec scan --stdio "python my_server.py" --ai

# 💥 Run Protocol Fuzzer (Find crashes)
mcpsec fuzz --stdio "python my_server.py" --duration 30

# Scan an MCP server running via HTTP  
mcpsec scan --http http://localhost:3000/mcp

# Just enumerate the attack surface (no scanning)
mcpsec info --stdio "python my_server.py"

# Save JSON report
mcpsec scan --stdio "python my_server.py" --output report.json

# Run specific scanners only
mcpsec scan --stdio "python my_server.py" --scanners prompt-injection,path-traversal

# Static Audit (Source Code Analysis)
mcpsec audit --path . --ai

# Scan NPM package (downloads and scans)
mcpsec audit --npm @modelcontextprotocol/server-filesystem

# List available scanners
mcpsec list-scanners

Scanners

Scanner	Type	What It Detects
prompt-injection	Static	Hidden instructions, base64-encoded payloads, cross-tool manipulation, data exfiltration indicators in tool descriptions
auth-audit	Static	Missing authentication, over-permissioned tools, dangerous tool combinations, misleading annotations
path-traversal	Dynamic	File path traversal via ../../ payloads — proves exploitation with actual file contents
command-injection	Dynamic	OS command injection via shell escape characters — proves exploitation with command output
ssrf	Dynamic	Server-Side Request Forgery targeting cloud metadata endpoints and internal services
ai-payloads	Dynamic	(New) Context-aware payloads generated by LLMs (SQLi, Logic bugs, Edge cases)
protocol-fuzzer	Dynamic	(New) Malformed JSON-RPC messages, boundary testing, type confusion to find crashes

Static scanners analyze tool definitions without calling them. Dynamic scanners send actual payloads through the MCP protocol and verify exploitability — no exploit, no report.

How It Works

┌─────────┐     MCP Protocol      ┌────────────┐
│ mcpsec  │ ◄──── JSON-RPC ────►  │ Target MCP │
│ client  │    (stdio or HTTP)    │   Server   │
└────┬────┘                       └────────────┘
     │
     ├── 1. Connect (stdio subprocess or HTTP)
     ├── 2. Enumerate tools, resources, prompts  
     ├── 3. Run static scanners (analyze descriptions)
     ├── 4. Generate & Run dynamic payloads (Fuzzing + AI)
     └── 5. Report findings with evidence + remediation

Example Output

  🔴 CRITICAL  Path Traversal detected in parameter 'filepath'
               scanner=path-traversal  tool=read_file
               Payload: ../../../../../../windows/win.ini
               Response: ; for 16-bit app support [fonts] [extensions] [Mail] MAPI=1

  🔴 CRITICAL  Command Injection detected in parameter 'target'
               scanner=command-injection  tool=run_diagnostics
               Payload: | whoami
               Response: intruder\username

  🧠 CRITICAL  AI Exploit: SQL Injection confirmed
               scanner=ai-sqli  tool=query_db
               Payload: ' OR 1=1 --
               Response: [Admin, User, Guest]

  ╔════════════╤═════════╗
  ║  CRITICAL  │      5  ║
  ║  HIGH      │      5  ║
  ║  MEDIUM    │      1  ║
  ║  LOW       │      8  ║
  ╟────────────┼─────────╢
  ║  TOTAL     │     19  ║
  ╚════════════╧═════════╝

Development

git clone https://github.com/manthanghasadiya/mcpsec.git
cd mcpsec
pip install -e ".[dev]"

# Run against the included deliberately-vulnerable test server
mcpsec scan --stdio "python tests/vuln_test_server.py"

The test server (tests/vuln_test_server.py) contains 8 intentional vulnerabilities covering prompt injection, command injection, path traversal, missing auth, and more. Use it to test scanner development.

Roadmap

• Prompt injection scanner (keyword, imperative, encoding, cross-tool, exfiltration detection)
• Authentication & authorization audit
• Path traversal scanner (dynamic, payload-based)
• Command injection scanner (dynamic, payload-based)
• SSRF scanner (dynamic, payload-based)
• JSON report output
• Static source code analysis mode (Taint Analysis & pattern matching)
• Cross-File Taint Analysis (Detects vulnerabilities spanning multiple files)
• Protocol Fuzzer (Crash detection & boundary testing)
• AI-Powered Analysis (Payload generation & Finding validation)
• SQL injection scanner (Automated with AI)
• Tool description drift detector (rug pull detection)
• HTML report dashboard
• SARIF output for CI/CD integration
• GitHub Action for automated MCP server security testing

Contributing

Contributions welcome! See CONTRIBUTING.md for details on how to set up your environment and add new scanners.

Disclaimer

This tool is intended for authorized security testing only. Only scan MCP servers you own or have explicit permission to test. The authors are not responsible for misuse.

License

MIT

---

Built by Manthan — because your AI agents deserve a pentest too.