MCPScan

A multi-stage security scanner for Model Context Protocol (MCP) based on the Agents.

📝 Paper coming soon

---

🔍 Overview

MCP Scanner is a lightweight but powerful tool for auditing AI agent tools and plugin ecosystems.

It integrates static taint analysis (via Semgrep rules) and dynamic LLM evaluation to detect:

• Malicious metadata (used in prompt injection)
• Insecure tool implementations (e.g., unsafe file reads)
• Code-level vulnerabilities in MCP-compatible services

Supports scanning local codebases or remote GitHub repositories.

📄 中文版文档 (Chinese README)

---

✨ Features

• Stage 1 (Semgrep Taint Scan)
  Detects taint sources and sinks via static rules.

• Stage 2 (Metadata Description Monitoring, Optional)
  Uses LLM to assess description fields — outputs labels: malicious, safe, suspect.

• Stage 3 (Cross-file Flow Extraction & Risk Judgment, Optional)
  Reconstructs code flow for high-risk patterns and gets final LLM risk verdicts (HIGH/LOW).

• Flexible CLI Control
  Toggle each stage, specify rulesets, customize output format.

---

🧠 Risks Detected

Category	Examples
🧬 Tool Metadata Pollution	LLM-injectable description content
🧪 Tool Poisoning	Malicious URLs or shell code embedded in tools
🔁 Indirect Prompt Injection	Unsafe tool output returns to LLM
🧰 Shadow Tool	Tool defined without proper registration
📤 Data Exfiltration	Sensitive file/network reads exposed to user
☠️ Malicious Code Snippets	Hardcoded command injection, eval(), os.system(), etc.

---

🧰 Installation

Prerequisites

• Python 3.8 or higher
• Semgrep
• DeepSeek API key

pip install semgrep
export DEEPSEEK_API_KEY="your_actual_api_key_here"

Install MCP Scanner

git clone https://github.com/antgroup/Trustworthy_LM.git
cd mcp-scanner
pip install -e .

After install, use mcpscan as a global CLI command.

---

⚙️ Configuration (Optional)

• Custom Semgrep rules: place in config/semgrep_rules.yml
• Specify alternate config: --config <FILE>

---

🚀 Usage

Basic Check

mcpscan --version
# mcpscan 0.1.0

CLI Options

Flag	Description	Default
<code_address>	Path or GitHub repo to scan	-
--config <FILE>	Custom Semgrep ruleset	config/semgrep_rules.yml
--monitor-desc / --no-monitor-desc	Enable LLM metadata analysis	✅ Enabled
--monitor-code / --no-monitor-code	Enable code flow scanning	✅ Enabled
--save / --no-save	Save JSON output	✅ Enabled
--out <FILE>	Output file name	triage_report.json

Commands

# Full scan of local repo
mcpscan scan ./my-repo

# Skip LLM metadata scan
mcpscan scan ./my-repo --no-monitor-desc

# Scan GitHub repo, no file save
mcpscan scan https://github.com/you/repo --no-monitor-code --no-save

# Custom rules + language override
mcpscan scan ./project -c config/semgrep_rules.yml --lang javascript

Example Commands

# SFull scan of local repo
mcpscan scan example/fetch


# Scan GitHub repo, no file save
mcpscan scan https://github.com/smithery-ai/mcp-fetch.git

---

🧭 Scan Workflow

Stage	Screenshot
Stage 1: Semgrep Scan Result
Stage 2: LLM Metadata Scan
Stage 3: Code Detection
Stage 4: Code Relate and Rist Judgement
Final Output (Terminal + JSON)

You can toggle stages with --monitor-desc, --monitor-code, and --save.

---

👨‍💻 Authors

This project is developed and maintained by: Zeyang Sha, Changhua Chen, Shiwen Cui, Changhua Meng, Weiqiang Wang.

---

🤝 Contributing

We welcome contributions via Issues or Pull Requests. If you're building secure LLM agents or need advanced MCP evaluation tooling, feel free to connect.

---

📄 Citation

If you use MCP Scanner in your research or product, please cite:

@misc{sha2025mcpscan,
  title={MCPSCAN},
  author={Zeyang Sha and Changhua Chen and Shiwen Cui and Changhua Meng and Weiqiang Wang},
  year={2025},
  url={https://github.com/antgroup/Trustworthy_LM/mcp-scan}
}

---

📜 License

This project is licensed under the Apache License 2.0.