https://github.com/aaronlab/mcp-shield

🛡️ MCP Server Security Auditor & Trust Dashboard — Scan, audit, and visualize your MCP server attack surface with trust scores (A-F), Rich CLI, and glassmorphism HTML reports
https://github.com/aaronlab/mcp-shield

ai-agent claude claude-code cli cybersecurity mcp mcp-server model-context-protocol python security security-audit trust-score

Last synced: 1 day ago
JSON representation

🛡️ MCP Server Security Auditor & Trust Dashboard — Scan, audit, and visualize your MCP server attack surface with trust scores (A-F), Rich CLI, and glassmorphism HTML reports

• Host: GitHub
• URL: https://github.com/aaronlab/mcp-shield
• Owner: aaronlab
• License: mit
• Created: 2026-04-02T02:23:20.000Z (2 months ago)
• Default Branch: main
• Last Pushed: 2026-04-02T02:23:22.000Z (2 months ago)
• Last Synced: 2026-05-09T15:53:22.449Z (25 days ago)
• Topics: ai-agent, claude, claude-code, cli, cybersecurity, mcp, mcp-server, model-context-protocol, python, security, security-audit, trust-score
• Language: Python
• Size: 30.3 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  



🛡️ 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)](https://modelcontextprotocol.io) 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 ` 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

```bash

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](https://github.com/Textualize/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:

```bash

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

```bash

mcp-shield scan

```

### HTML trust dashboard

```bash

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

```bash

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

```bash

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

```

### Get remediation steps

```bash

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+

```bash

# 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`](https://github.com/Textualize/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](CONTRIBUTING.md) for detailed guidelines.

---

## 📄 License

MIT © [AARON AGENT](https://github.com/aaronagent)

---

## ⭐ 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 集成）

- **修复指引** — 逐步指导修复每一项安全发现

### 快速开始

```bash

pip install mcp-shield

# 扫描所有已发现的 MCP 服务器

mcp-shield scan

# 生成 HTML 报告

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

# 查看修复建议

mcp-shield fix 

```

### 参与贡献

欢迎提交 Issue 和 Pull Request！详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

---



  Built with 🔒 by AARON AGENT


  Securing the AI agent ecosystem, one MCP server at a time.