🛡️ MCP Shield

Security Auditor & Trust Dashboard for MCP Servers
Scan. Score. Secure — before your AI agent gets compromised.

---

MCP Shield is a CLI tool that automatically discovers your locally configured MCP (Model Context Protocol) servers, runs 8 categories of security checks, assigns a trust score (A–F), and generates beautiful reports — all in one command.

$ mcp-shield scan

  ╔══════════════════════════════════════════════════════════════╗
  ║                  🛡️  MCP Shield v1.0                        ║
  ║              Security Auditor & Trust Dashboard              ║
  ╚══════════════════════════════════════════════════════════════╝

  📍 Discovered 4 MCP servers across 3 config files

  ┌──────────────────┬───────┬───────┬──────────────────────────┐
  │ Server           │ Score │ Grade │ Top Finding              │
  ├──────────────────┼───────┼───────┼──────────────────────────┤
  │ filesystem       │  85   │   A   │ SCOPE-001: broad perms   │
  │ github           │  72   │   B   │ ENV-002: hardcoded token │
  │ puppeteer        │  41   │   D   │ NET-001: binds 0.0.0.0   │
  │ sketchy-mcp      │  18   │   F   │ KNOWN-001: risky package │
  └──────────────────┴───────┴───────┴──────────────────────────┘

  ⚠  Overall Trust Score: 54 / 100 (C)
  💡 Run `mcp-shield fix <server>` for remediation steps.

MCP is the backbone of AI agent tooling in 2026 — but most servers run with zero security review. MCP Shield changes that.

---

⚡ Quick Start

pip install mcp-shield

# Scan all auto-discovered MCP servers
mcp-shield scan

# Generate an HTML trust dashboard
mcp-shield scan --format html -o report.html

# Get remediation guidance for a specific server
mcp-shield fix filesystem

That's it. No config files, no API keys, no setup.

---

🤔 Why MCP Shield?

MCP servers are the new attack surface of the AI agent era. A single misconfigured server can:

• 🔓 Leak API keys and secrets — hardcoded tokens in env vars or command args
• 🌍 Expose local services to the internet — servers binding to 0.0.0.0 without intent
• 💉 Enable command injection — shell invocations in server startup commands
• 📤 Exfiltrate your data — servers with both filesystem and network access
• 🎭 Run typosquatted packages — unscoped npx/uvx installs from public registries

Most developers configure MCP servers once and never audit them again. MCP Shield gives you continuous visibility with a single command.

---

✨ Features

Feature	Description
Auto-Discovery	Finds servers from Claude Code, Cursor, and project-level configs automatically
8 Security Check Categories	15+ individual rules across scope, command, env, package, network, exfiltration, known-risk, and privilege checks
Trust Scoring	0–100 score with A–F letter grades, per-server and overall
Rich CLI Output	ASCII art banners, colored tables, severity-coded findings via Rich
HTML Dashboard	Glassmorphism dark-theme report with animated SVG trust gauges
JSON Export	Machine-readable output for CI/CD pipelines
Guided Remediation	mcp-shield fix provides step-by-step fixes for each finding
Zero Config	Works out of the box — just install and scan

---

📍 Auto-Discovery

MCP Shield knows where to look. It automatically scans:

Client	Config Paths
Claude Code	~/.claude/settings.json, ~/.claude.json
Cursor	~/.cursor/mcp.json
Project-level	.mcp.json, .cursor/mcp.json in current directory

Pass --path to scan any custom config location:

mcp-shield scan --path /path/to/custom/config.json

---

🔍 Security Checks Reference

ID	Category	Severity	What It Detects
SCOPE-001	Scope	🔴 High	Wildcard (*) in permission allow-lists
SCOPE-002	Scope	🟡 Medium	Missing permission allow-list entirely
CMD-001	Command	🔴 High	Shell invocation (sh -c, bash -c, cmd /c)
CMD-002	Command	🟡 Medium	Command injection risk via string interpolation
ENV-001	Environment	🟡 Medium	Sensitive env var names (*_KEY, *_SECRET, *_TOKEN)
ENV-002	Environment	🔴 High	Hardcoded secrets (API keys, tokens in plaintext)
PKG-001	Package	🟡 Medium	Unscoped npx package (typosquatting risk)
PKG-002	Package	🟡 Medium	Unscoped uvx package (typosquatting risk)
NET-001	Network	🔴 High	Server binding to 0.0.0.0 (all interfaces)
NET-002	Network	🟡 Medium	Explicit port exposure in arguments
EXFIL-001	Exfiltration	🔴 High	Combined filesystem + network access (data exfil risk)
EXFIL-002	Exfiltration	🟡 Medium	Write access to sensitive paths with outbound network
KNOWN-001	Known Risk	🔴 High	Package found in known-risky MCP server database
PRIV-001	Privilege	🔴 High	sudo in server command
PRIV-002	Privilege	🔴 High	Running as root
PRIV-003	Privilege	🔴 High	Docker --privileged flag

---

🎯 Usage Examples

Basic scan

mcp-shield scan

HTML trust dashboard

mcp-shield scan --format html -o report.html

Generates a dark-theme glassmorphism dashboard with animated SVG trust-score gauges, per-server breakdowns, and finding details. Open report.html in any browser.

JSON output for CI/CD

mcp-shield scan --format json

# Use in CI pipelines — fail if overall grade is below B
mcp-shield scan --format json | jq -e '.overall_grade <= "B"'

Scan a specific config

mcp-shield scan --path ~/.cursor/mcp.json

Get remediation steps

mcp-shield fix puppeteer

  🔧 Remediation for: puppeteer

  NET-001 (High) — Server binds to 0.0.0.0
  ├─ Risk:  Exposes server to all network interfaces
  ├─ Fix:   Change bind address to 127.0.0.1
  └─ Where: args: ["--host", "0.0.0.0"] → ["--host", "127.0.0.1"]

  SCOPE-001 (High) — Wildcard permission allow-list
  ├─ Risk:  Server has unrestricted tool access
  ├─ Fix:   Explicitly list only the tools you need
  └─ Ref:   https://modelcontextprotocol.io/docs/security

---

🏗️ Trust Scoring

Each server receives a 0–100 trust score based on weighted findings:

Grade	Score	Meaning
A	90–100	Excellent — minimal or no issues
B	80–89	Good — minor issues only
C	65–79	Fair — moderate risks present
D	50–64	Poor — significant security concerns
F	0–49	Failing — critical risks, immediate action needed

Scoring weights: 🔴 High findings deduct 15 pts, 🟡 Medium deduct 5 pts, 🔵 Low deduct 2 pts.

---

🛠️ Installation

Requirements: Python 3.9+

# From PyPI (recommended)
pip install mcp-shield

# From source
git clone https://github.com/aaronagent/mcp-shield.git
cd mcp-shield
pip install -e .

The only runtime dependency is rich for CLI output.

---

🤝 Contributing

Contributions are welcome! Here's how to get involved:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/new-check)
3. Commit your changes (git commit -m 'Add new security check')
4. Push to the branch (git push origin feat/new-check)
5. Open a Pull Request

Areas where help is wanted

• 🆕 New security check rules
• 🌐 Support for more MCP clients (VS Code, Windsurf, etc.)
• 🧪 Test coverage
• 📖 Documentation and translations
• 🐛 Bug reports and feature requests

Please see CONTRIBUTING.md for detailed guidelines.

---

📄 License

MIT © AARON AGENT

---

⭐ Star History

If MCP Shield helped secure your AI agent setup, consider giving it a ⭐ — it helps others discover the project.

---

中文说明

🛡️ MCP Shield — MCP 服务器安全审计工具

MCP Shield 是一款命令行工具，专为 AI Agent 生态中的 MCP（模型上下文协议）服务器 提供安全扫描和信任评估。

为什么需要 MCP Shield？

2026 年，MCP 已成为 AI Agent 工具链的核心协议。然而，大多数开发者在配置 MCP 服务器后从未进行过安全审计。一个错误配置的服务器可能导致：

• 🔑 API 密钥和凭据泄露
• 🌐 本地服务意外暴露到公网
• 💉 命令注入攻击
• 📤 敏感数据被窃取
• 🎭 恶意包通过 typosquatting 入侵

核心功能

• 自动发现 — 自动扫描 Claude Code、Cursor 等客户端的 MCP 配置文件
• 8 大类安全检查 — 覆盖权限、命令、环境变量、包管理、网络、数据外泄、已知风险、特权提升
• 信任评分 — 0–100 分，A–F 等级评估
• 多种输出格式 — 彩色终端表格、HTML 可视化仪表盘、JSON（支持 CI/CD 集成）
• 修复指引 — 逐步指导修复每一项安全发现

快速开始

pip install mcp-shield

# 扫描所有已发现的 MCP 服务器
mcp-shield scan

# 生成 HTML 报告
mcp-shield scan --format html -o report.html

# 查看修复建议
mcp-shield fix <server-name>

参与贡献

欢迎提交 Issue 和 Pull Request！详见 CONTRIBUTING.md。

---

Built with 🔒 by AARON AGENT
Securing the AI agent ecosystem, one MCP server at a time.