{"id":50508970,"url":"https://github.com/aaronlab/mcp-shield","last_synced_at":"2026-06-02T18:32:50.577Z","repository":{"id":356747333,"uuid":"1199049661","full_name":"aaronlab/mcp-shield","owner":"aaronlab","description":"🛡️ MCP Server Security Auditor \u0026 Trust Dashboard — Scan, audit, and visualize your MCP server attack surface with trust scores (A-F), Rich CLI, and glassmorphism HTML reports","archived":false,"fork":false,"pushed_at":"2026-04-02T02:23:22.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T15:53:22.449Z","etag":null,"topics":["ai-agent","claude","claude-code","cli","cybersecurity","mcp","mcp-server","model-context-protocol","python","security","security-audit","trust-score"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T02:23:20.000Z","updated_at":"2026-04-02T02:23:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aaronlab/mcp-shield","commit_stats":null,"previous_names":["aaronlab/mcp-shield"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aaronlab/mcp-shield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fmcp-shield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fmcp-shield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fmcp-shield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fmcp-shield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronlab","download_url":"https://codeload.github.com/aaronlab/mcp-shield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronlab%2Fmcp-shield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33833277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude","claude-code","cli","cybersecurity","mcp","mcp-server","model-context-protocol","python","security","security-audit","trust-score"],"created_at":"2026-06-02T18:32:49.654Z","updated_at":"2026-06-02T18:32:50.564Z","avatar_url":"https://github.com/aaronlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-Shield-blue?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAxTDMgNXY2YzAgNS41NSAzLjg0IDEwLjc0IDkgMTIgNS4xNi0xLjI2IDktNi40NSA5LTEyVjVsLTktNHoiLz48L3N2Zz4=\" alt=\"MCP Shield\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e🛡️ MCP Shield\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eSecurity Auditor \u0026 Trust Dashboard for MCP Servers\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eScan. Score. Secure — before your AI agent gets compromised.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/mcp-shield/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/mcp-shield?color=blue\u0026label=PyPI\" alt=\"PyPI\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/mcp-shield/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/mcp-shield?color=blue\" alt=\"Python 3.9+\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/aaronagent/mcp-shield/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/aaronagent/mcp-shield?color=green\" alt=\"MIT License\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/aaronagent/mcp-shield/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/aaronagent/mcp-shield?style=social\" alt=\"GitHub Stars\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nMCP 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.\n\n```\n$ mcp-shield scan\n\n  ╔══════════════════════════════════════════════════════════════╗\n  ║                  🛡️  MCP Shield v1.0                        ║\n  ║              Security Auditor \u0026 Trust Dashboard              ║\n  ╚══════════════════════════════════════════════════════════════╝\n\n  📍 Discovered 4 MCP servers across 3 config files\n\n  ┌──────────────────┬───────┬───────┬──────────────────────────┐\n  │ Server           │ Score │ Grade │ Top Finding              │\n  ├──────────────────┼───────┼───────┼──────────────────────────┤\n  │ filesystem       │  85   │   A   │ SCOPE-001: broad perms   │\n  │ github           │  72   │   B   │ ENV-002: hardcoded token │\n  │ puppeteer        │  41   │   D   │ NET-001: binds 0.0.0.0   │\n  │ sketchy-mcp      │  18   │   F   │ KNOWN-001: risky package │\n  └──────────────────┴───────┴───────┴──────────────────────────┘\n\n  ⚠  Overall Trust Score: 54 / 100 (C)\n  💡 Run `mcp-shield fix \u003cserver\u003e` for remediation steps.\n```\n\n\u003e **MCP is the backbone of AI agent tooling in 2026 — but most servers run with zero security review.** MCP Shield changes that.\n\n---\n\n## ⚡ Quick Start\n\n```bash\npip install mcp-shield\n\n# Scan all auto-discovered MCP servers\nmcp-shield scan\n\n# Generate an HTML trust dashboard\nmcp-shield scan --format html -o report.html\n\n# Get remediation guidance for a specific server\nmcp-shield fix filesystem\n```\n\nThat's it. No config files, no API keys, no setup.\n\n---\n\n## 🤔 Why MCP Shield?\n\nMCP servers are the **new attack surface** of the AI agent era. A single misconfigured server can:\n\n- 🔓 **Leak API keys and secrets** — hardcoded tokens in env vars or command args\n- 🌍 **Expose local services to the internet** — servers binding to `0.0.0.0` without intent\n- 💉 **Enable command injection** — shell invocations in server startup commands\n- 📤 **Exfiltrate your data** — servers with both filesystem and network access\n- 🎭 **Run typosquatted packages** — unscoped `npx`/`uvx` installs from public registries\n\nMost developers configure MCP servers once and never audit them again. MCP Shield gives you **continuous visibility** with a single command.\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|---|---|\n| **Auto-Discovery** | Finds servers from Claude Code, Cursor, and project-level configs automatically |\n| **8 Security Check Categories** | 15+ individual rules across scope, command, env, package, network, exfiltration, known-risk, and privilege checks |\n| **Trust Scoring** | 0–100 score with A–F letter grades, per-server and overall |\n| **Rich CLI Output** | ASCII art banners, colored tables, severity-coded findings via [Rich](https://github.com/Textualize/rich) |\n| **HTML Dashboard** | Glassmorphism dark-theme report with animated SVG trust gauges |\n| **JSON Export** | Machine-readable output for CI/CD pipelines |\n| **Guided Remediation** | `mcp-shield fix` provides step-by-step fixes for each finding |\n| **Zero Config** | Works out of the box — just install and scan |\n\n---\n\n## 📍 Auto-Discovery\n\nMCP Shield knows where to look. It automatically scans:\n\n| Client | Config Paths |\n|---|---|\n| **Claude Code** | `~/.claude/settings.json`, `~/.claude.json` |\n| **Cursor** | `~/.cursor/mcp.json` |\n| **Project-level** | `.mcp.json`, `.cursor/mcp.json` in current directory |\n\nPass `--path` to scan any custom config location:\n\n```bash\nmcp-shield scan --path /path/to/custom/config.json\n```\n\n---\n\n## 🔍 Security Checks Reference\n\n| ID | Category | Severity | What It Detects |\n|---|---|---|---|\n| `SCOPE-001` | Scope | 🔴 High | Wildcard (`*`) in permission allow-lists |\n| `SCOPE-002` | Scope | 🟡 Medium | Missing permission allow-list entirely |\n| `CMD-001` | Command | 🔴 High | Shell invocation (`sh -c`, `bash -c`, `cmd /c`) |\n| `CMD-002` | Command | 🟡 Medium | Command injection risk via string interpolation |\n| `ENV-001` | Environment | 🟡 Medium | Sensitive env var names (`*_KEY`, `*_SECRET`, `*_TOKEN`) |\n| `ENV-002` | Environment | 🔴 High | Hardcoded secrets (API keys, tokens in plaintext) |\n| `PKG-001` | Package | 🟡 Medium | Unscoped `npx` package (typosquatting risk) |\n| `PKG-002` | Package | 🟡 Medium | Unscoped `uvx` package (typosquatting risk) |\n| `NET-001` | Network | 🔴 High | Server binding to `0.0.0.0` (all interfaces) |\n| `NET-002` | Network | 🟡 Medium | Explicit port exposure in arguments |\n| `EXFIL-001` | Exfiltration | 🔴 High | Combined filesystem + network access (data exfil risk) |\n| `EXFIL-002` | Exfiltration | 🟡 Medium | Write access to sensitive paths with outbound network |\n| `KNOWN-001` | Known Risk | 🔴 High | Package found in known-risky MCP server database |\n| `PRIV-001` | Privilege | 🔴 High | `sudo` in server command |\n| `PRIV-002` | Privilege | 🔴 High | Running as `root` |\n| `PRIV-003` | Privilege | 🔴 High | Docker `--privileged` flag |\n\n---\n\n## 🎯 Usage Examples\n\n### Basic scan\n\n```bash\nmcp-shield scan\n```\n\n### HTML trust dashboard\n\n```bash\nmcp-shield scan --format html -o report.html\n```\n\nGenerates a dark-theme glassmorphism dashboard with animated SVG trust-score gauges, per-server breakdowns, and finding details. Open `report.html` in any browser.\n\n### JSON output for CI/CD\n\n```bash\nmcp-shield scan --format json\n\n# Use in CI pipelines — fail if overall grade is below B\nmcp-shield scan --format json | jq -e '.overall_grade \u003c= \"B\"'\n```\n\n### Scan a specific config\n\n```bash\nmcp-shield scan --path ~/.cursor/mcp.json\n```\n\n### Get remediation steps\n\n```bash\nmcp-shield fix puppeteer\n```\n\n```\n  🔧 Remediation for: puppeteer\n\n  NET-001 (High) — Server binds to 0.0.0.0\n  ├─ Risk:  Exposes server to all network interfaces\n  ├─ Fix:   Change bind address to 127.0.0.1\n  └─ Where: args: [\"--host\", \"0.0.0.0\"] → [\"--host\", \"127.0.0.1\"]\n\n  SCOPE-001 (High) — Wildcard permission allow-list\n  ├─ Risk:  Server has unrestricted tool access\n  ├─ Fix:   Explicitly list only the tools you need\n  └─ Ref:   https://modelcontextprotocol.io/docs/security\n```\n\n---\n\n## 🏗️ Trust Scoring\n\nEach server receives a **0–100 trust score** based on weighted findings:\n\n| Grade | Score | Meaning |\n|---|---|---|\n| **A** | 90–100 | Excellent — minimal or no issues |\n| **B** | 80–89 | Good — minor issues only |\n| **C** | 65–79 | Fair — moderate risks present |\n| **D** | 50–64 | Poor — significant security concerns |\n| **F** | 0–49 | Failing — critical risks, immediate action needed |\n\nScoring weights: 🔴 High findings deduct **15 pts**, 🟡 Medium deduct **5 pts**, 🔵 Low deduct **2 pts**.\n\n---\n\n## 🛠️ Installation\n\n**Requirements:** Python 3.9+\n\n```bash\n# From PyPI (recommended)\npip install mcp-shield\n\n# From source\ngit clone https://github.com/aaronagent/mcp-shield.git\ncd mcp-shield\npip install -e .\n```\n\nThe only runtime dependency is [`rich`](https://github.com/Textualize/rich) for CLI output.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how to get involved:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feat/new-check`)\n3. **Commit** your changes (`git commit -m 'Add new security check'`)\n4. **Push** to the branch (`git push origin feat/new-check`)\n5. **Open** a Pull Request\n\n### Areas where help is wanted\n\n- 🆕 New security check rules\n- 🌐 Support for more MCP clients (VS Code, Windsurf, etc.)\n- 🧪 Test coverage\n- 📖 Documentation and translations\n- 🐛 Bug reports and feature requests\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## 📄 License\n\nMIT © [AARON AGENT](https://github.com/aaronagent)\n\n---\n\n## ⭐ Star History\n\nIf MCP Shield helped secure your AI agent setup, consider giving it a ⭐ — it helps others discover the project.\n\n\u003ca href=\"https://github.com/aaronagent/mcp-shield/stargazers\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/aaronagent/mcp-shield?style=social\" alt=\"Star on GitHub\"/\u003e\n\u003c/a\u003e\n\n---\n\n## 中文说明\n\n### 🛡️ MCP Shield — MCP 服务器安全审计工具\n\nMCP Shield 是一款命令行工具，专为 AI Agent 生态中的 **MCP（模型上下文协议）服务器** 提供安全扫描和信任评估。\n\n### 为什么需要 MCP Shield？\n\n2026 年，MCP 已成为 AI Agent 工具链的核心协议。然而，大多数开发者在配置 MCP 服务器后从未进行过安全审计。一个错误配置的服务器可能导致：\n\n- 🔑 API 密钥和凭据泄露\n- 🌐 本地服务意外暴露到公网\n- 💉 命令注入攻击\n- 📤 敏感数据被窃取\n- 🎭 恶意包通过 typosquatting 入侵\n\n### 核心功能\n\n- **自动发现** — 自动扫描 Claude Code、Cursor 等客户端的 MCP 配置文件\n- **8 大类安全检查** — 覆盖权限、命令、环境变量、包管理、网络、数据外泄、已知风险、特权提升\n- **信任评分** — 0–100 分，A–F 等级评估\n- **多种输出格式** — 彩色终端表格、HTML 可视化仪表盘、JSON（支持 CI/CD 集成）\n- **修复指引** — 逐步指导修复每一项安全发现\n\n### 快速开始\n\n```bash\npip install mcp-shield\n\n# 扫描所有已发现的 MCP 服务器\nmcp-shield scan\n\n# 生成 HTML 报告\nmcp-shield scan --format html -o report.html\n\n# 查看修复建议\nmcp-shield fix \u003cserver-name\u003e\n```\n\n### 参与贡献\n\n欢迎提交 Issue 和 Pull Request！详见 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuilt with 🔒 by \u003ca href=\"https://github.com/aaronagent\"\u003eAARON AGENT\u003c/a\u003e\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eSecuring the AI agent ecosystem, one MCP server at a time.\u003c/em\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronlab%2Fmcp-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronlab%2Fmcp-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronlab%2Fmcp-shield/lists"}