Metadata-Version: 2.3
Name: mcpsec
Version: 0.4.0
Summary: Security scanner for MCP (Model Context Protocol) server implementations
Project-URL: Homepage, https://github.com/manthanghasadiya/mcpsec
Project-URL: Repository, https://github.com/manthanghasadiya/mcpsec
Author: Manthan
License: MIT
Keywords: ai,mcp,model-context-protocol,pentesting,scanner,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: semgrep>=1.90.0
Requires-Dist: typer>=0.12.0
Provides-Extra: ai
Requires-Dist: openai>=1.0.0; extra == 'ai'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# ⚡ mcpsec

[![License: MIT](https://img.shields.io/badge/License-MIT-cyan.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

**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](https://www.endorlabs.com/learn/classic-vulnerabilities-meet-ai-infrastructure-why-mcp-needs-appsec))
- **67%** are vulnerable to code injection
- **~2,000** internet-exposed MCP servers found with **zero authentication** ([Knostic](https://www.descope.com/learn/post/mcp))
- 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

```bash
pip install mcpsec
```

Or install from source:

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

## Quick Start

```bash
# 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

```bash
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

- [x] Prompt injection scanner (keyword, imperative, encoding, cross-tool, exfiltration detection)
- [x] Authentication & authorization audit
- [x] Path traversal scanner (dynamic, payload-based)
- [x] Command injection scanner (dynamic, payload-based)
- [x] SSRF scanner (dynamic, payload-based)
- [x] JSON report output
- [x] **Static source code analysis mode** (Taint Analysis & pattern matching)
- [x] **Cross-File Taint Analysis** (Detects vulnerabilities spanning multiple files)
- [x] **Protocol Fuzzer** (Crash detection & boundary testing)
- [x] **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](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](LICENSE)

---

*Built by [Manthan](https://www.linkedin.com/in/man-ghasadiya) — because your AI agents deserve a pentest too.*
