使用说明
Find security vulnerabilities in your MCP server configs before attackers do.
Maps every finding to the OWASP MCP Top 10. Zero config. Runs locally.
快速开始
pip install guardmcp
mcpguard scan
就是这样。mcpguard从Claude Desktop、Claude Code、Cursor、VS Code和Windsurf自动检测MCP配置。没有API密钥，没有帐户，一切都在本地运行。
它扫描什么
mcpguard根据 OWASP MCP前10名:
| 风险 | mcpguard检测到什么 | |
|---|---|---|
| Y MCP01 代币和秘密曝光 | 硬编码API密钥（AWS、OpenAI、GitHub、Anthropic、Stripe）、高熵秘密、JWT代币、实时秘密验证 | |
| Y MCP02 特权升级 | 通配符 alwaysAllow，工具范围权限过大 |
|
| Y MCP03 工具中毒 | 工具描述中的14种注射模式、可疑名称、长篇描述、工具阴影、地毯拉扯检测 | |
| Y MCP04 供应链攻击 | 未加密 @latest 版本，缺少版本锁 |
|
| Y MCP05 命令注入 | Shell元字符、危险命令、缺少输入模式 | |
| Y MCP06 意图颠覆 | SSRF倾向的URL（云元数据、私有IP） | |
| Y MCP07 缺少身份验证 | 没有身份验证标头的HTTP服务器，明文HTTP传输 | |
| Y MCP08 无审核日志 | 不安全的shell执行，args中的管道/重定向 | |
| Y MCP09 影子服务器 | 本地主机/开发URL，未注册的服务器 | |
| Y MCP10 上下文过度共享 | Docker主机网络，敏感卷挂载，无速率限制 |
特性
- 零配置 --自动发现来自5个MCP客户端的配置
- OWASP已映射 --每个发现都链接到OWASP MCP Top 10
- 16条检测规则 --机密、身份验证、权限、供应链、注入、影子服务器
- 基于熵的秘密检测 --捕捉与已知模式不匹配的秘密
- 自动修正 --
mcpguard fix将硬编码的秘密替换为${VAR}参考文献 - 自定义规则 --添加自己的YAML检测规则
- SARIF输出 --与GitHub安全选项卡集成
- GitHub行动 --插入式CI/CD安全门
- 预提交挂钩 --在问题提交之前将其抓住
- 无网络 --一切都在本地运行，没有API调用
用法
# Scan all auto-detected configs
mcpguard scan
# Scan a specific config file
mcpguard scan --path /path/to/mcp.json
# Auto-fix hardcoded secrets, HTTP URLs, wildcard permissions
mcpguard fix
# Preview fixes without modifying files
mcpguard fix --dry-run
# JSON output for CI/CD
mcpguard scan --format json
# SARIF output for GitHub Security tab
mcpguard scan --format sarif -o results.sarif
# Only show critical and high findings
mcpguard scan --severity high
# Connect to servers and inspect tool definitions
mcpguard inspect
# Verify detected secrets are live (makes read-only API calls)
mcpguard scan --verify
# Quick pass/fail check (exit code only)
mcpguard check
# Add custom detection rules
mcpguard scan --rules-dir ./my-rules/
自动修正
mcpguard可以自动修复常见的安全问题：
mcpguard fix
它修复了什么：
- 将硬编码API密钥替换为
${VAR_NAME}环境变量引用 - 升级
http://URL指向https:// - 删除通配符
alwaysAllow: ["*"] - 创建一个
.mcpguard-backup在修改任何文件之前
支持的客户
| 客户端 | 配置位置 |
|---|---|
| 克劳德桌面 | ~/Library/Application Support/Claude/claude_desktop_config.json |
| 克劳德代码 | ~/.claude.json, .mcp.json |
| 光标 | ~/.cursor/mcp.json, .cursor/mcp.json |
| VS代码 | ~/.config/Code/User/mcp.json, .vscode/mcp.json |
| 风帆冲浪 | ~/.codeium/windsurf/mcp_config.json |
自定义规则
mcpguard使用YAML检测规则。添加您自己的：
id: CUSTOM-001
info:
name: Internal API Key Pattern
severity: critical
owasp: MCP01
description: Detects internal API keys
remediation: Use vault references
cwe: CWE-798
detection:
target: config
scope: env_values
match:
type: regex
patterns:
- 'internal_[a-z0-9]{32}'
mcpguard scan --rules-dir ./my-rules/
GitHub行动
name: MCP Security Scan
on: [push, pull_request]
jobs:
mcpguard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: loplop-h/mcpguard@v1
或手动：
- run: pip install guardmcp
- run: mcpguard scan --format sarif -o results.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
预提交钩子
# .pre-commit-config.yaml
repos:
- repo: https://github.com/loplop-h/mcpguard
rev: v0.1.0
hooks:
- id: mcpguard
如何比较
| 功能 | mcpguard | mcp扫描 | 腾讯AI Infra Guard | 思科mcp扫描仪 |
|---|---|---|---|---|
| 零配置CLI | Y | Y | N（Docker/web） | N（API密钥） |
| 配置扫描 | 和 | 和 | 和 | |
| 服务器检查 | Y | Y | Y | N |
| 刀具中毒检测 | Y（14种模式） | Y | 部分 | N |
| Rug pull检测 | Y（哈希钉扎） | Y | N | N |
自动修复(fix) |
Y | N | N | N |
| OWASP MCP十大地图 | Y（10/10） | N | N | N |
| 秘密验证 | Y （GitHub、OpenAI、Anthropic、Stripe） | N | N | N |
| SARIF输出 | Y | N | N | N |
| GitHub行动 | Y | N | N | N |
| 预提交挂钩 | Y | N | N | N |
| 自定义YAML规则 | Y | N | N | N |
| 基于熵的检测 | Y | N | N | N |
隐私
- 所有数据都保留在您的机器上
- 没有遥测，没有跟踪
scan仅读取配置文件（无网络）inspect仅连接到本地stdio服务器（从不向外部发送数据）--verify进行只读API调用以检查机密是否处于活动状态- 开源，麻省理工学院授权
贡献
git clone https://github.com/loplop-h/mcpguard.git
cd mcpguard
pip install -e ".[dev]"
pytest
在中添加检测规则 src/mcpguard/rules/ 使用上面的YAML模式。
许可证
麻省理工学院
