MCP Security Guard

MCP 安全卫士

查明你安装的 MCP 服务是否在欺骗你的 AI。

本地审计工具中毒、突然变更、工具遮蔽、隐藏 Unicode 字符和泄露的机密，并映射到 OWASP MCP Top 10。除非你选择主动分享，否则不会有任何数据离开你的设备。

---

🚀 快速安装

Cursor

点击上方按钮，或使用此深层链接：cursor://anysphere.cursor-deeplink/mcp/install?name=mcp-security-guard&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1zZWN1cml0eS1ndWFyZCJdfQ==

或者手动添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "mcp-security-guard": {
      "command": "npx",
      "args": ["-y", "mcp-security-guard"]
    }
  }
}

Claude Code

通过插件（推荐）

/plugin marketplace add petrovicistefan/mcp-security-guard
/plugin install mcp-security-guard@mcp-security-guard

然后运行 /mcp-audit，或询问 Claude “我的 MCP 服务安全吗？”

通过 CLI

claude mcp add mcp-security-guard -- npx -y mcp-security-guard

Claude Desktop

添加到你的 Claude Desktop 配置中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "mcp-security-guard": {
      "command": "npx",
      "args": ["-y", "mcp-security-guard"]
    }
  }
}

VS Code

点击上方按钮，或手动添加到 .vscode/mcp.json：

{
  "mcpServers": {
    "mcp-security-guard": {
      "command": "npx",
      "args": ["-y", "mcp-security-guard"]
    }
  }
}

命令行

npx -y mcp-security-guard audit --project-only

⭐ 为此仓库点星，支持项目并获取最新动态！ → 点个星

---

---

📋 目录

• 为什么选择 MCP Security Guard？
• 使用场景
• 检查内容
• OWASP MCP Top 10 覆盖范围
• 快速演示（1 分钟）
• 工具
• CI / GitHub Action
• 交互式仪表板
• 运行时钩子
• 团队计划（付费，可选）
• 基准测试结果
• 开发
• 参与贡献
• 安全与隐私
• 关于作者

---

为什么选择 MCP Security Guard？

其他工具会保护你的代码。这个工具会检查那些向 AI 上下文注入文本的 MCP 服务。

MCP Security Guard 会审计 Claude（以及其他 AI 客户端）能够访问的每个 MCP 服务：你配置的服务、插件引入的服务，以及你设备上 Claude Desktop 和其他客户端提供的服务。

对比

截至 2026 年 10 月。欢迎指正。

功能	MCP Security Guard	snyk/agent-scan	cisco-ai-defense/mcp-scanner	riseandignite/mcp-shield
Claude Code 原生插件	✅	❌	❌	❌
运行时钩子（工具调用前/后）	✅	❌	❌	❌
防篡改固定（SHA-256）	✅ 工具、技能、CLAUDE.md	有限	❌	❌
OWASP MCP Top 10 映射	✅ 每项发现	❌	❌	❌
SARIF 输出	✅ GitHub Action	❌	❌	❌
CycloneDX BOM 导出	✅ Agent 清单	❌	❌	❌
完全本地运行（零网络）	✅ 默认	各不相同	各不相同	各不相同
供应链检查	✅ OSV、npm、PyPI	各不相同	各不相同	各不相同
工具投毒检测	✅ 26/27 种攻击	各不相同	各不相同	各不相同
许可证	MIT	Apache 2.0	MIT	MIT

我们的差异化优势：

• 原生集成 Claude Code，提供 /mcp-audit 斜杠命令和运行时防护
• 全面防范篡改：固定并验证工具定义、技能、命令、子 Agent 和 CLAUDE.md 文件
• 每项发现均映射到 OWASP MCP Top 10，为合规和修复提供指导
• 提供带 SARIF 的 GitHub Action，在拉取请求中生成代码扫描警报
• 以 CycloneDX 1.6 格式提供 Agent 物料清单（BOM），用于审计和合规
• 隐私优先：默认在本地运行所有操作；网络访问需明确选择启用

---

使用场景

1. 个人开发者

保护你的本地 AI 环境。

• 在安装前后审计 MCP 服务
• 当服务的工具定义发生变化（篡改）时收到警告
• 运行时防护：阻止发送凭据，检测受污染的输出
• 固定可信的服务和技能，以便持续验证

# Scan before installing a new server
npx mcp-security-guard scan server-config.json --confirm-launch

# Pin your reviewed servers
npx mcp-security-guard pin

# Check everything is still safe
npx mcp-security-guard audit

2. 拉取请求 CI 检查

在代码审查中拦截高风险的 MCP 服务和受污染的技能。

以下情况会导致 PR 失败：

• 添加了存在工具投毒、未固定软件包或特权 Docker 镜像的 MCP 服务
• 添加了包含指令覆盖或凭据外泄内容的技能或 CLAUDE.md 文件
• 添加了有漏洞的依赖项或仿冒软件包

发现结果会显示在 GitHub 的代码扫描界面中，并附有 OWASP MCP Top 10 参考信息。

- uses: petrovicistefan/mcp-security-guard@main
  with:
    fail-on: high

3. 团队和企业

为组织制定统一的安全策略。

使用 Team 计划（付费，需主动启用）：

• 管理员发布一项策略（允许/阻止的服务、插件和固定版本）
• 每个人的插件都会自动执行该策略，即使处于离线状态也不例外
• 审批流程：开发者提交申请，管理员批准
• 设备清单：查看团队运行的 MCP 服务（需主动启用并征得同意）
• 合规证据：用于审计的 OWASP MCP Top 10 覆盖报告

---

检查内容

MCP Security Guard 会发现 AI 客户端加载服务器的所有位置：用户级、本地级和项目级配置、已安装插件内附带的服务器、claude_desktop_config.json、Claude Desktop 扩展、组织管理的 managed-mcp.json、计算机上的其他客户端（Cursor、VS Code、Windsurf），以及你使用过的 claude.ai 连接器。

它会扫描服务器放入 AI 上下文的所有内容：工具、服务器指令、提示词、资源和资源模板。

检查项	检查内容
工具投毒	指令覆盖、“不要告诉用户”、<IMPORTANT> 标签、读取机密（~/.ssh、.env）的指令、对话内容收集、通过 URL／参数／Markdown 图片外传数据、HTML 注释、编码载荷
完整架构投毒	对参数名称、描述、默认值、枚举、required 执行相同检查，并检查 type 中非架构文本
隐藏文本	零宽字符、双向控制字符和 Unicode 标签字符、ANSI 终端转义序列、易混淆字符构成的工具名称
工具冒名	服务器描述中引用其他服务器的工具、服务器间工具名称冲突
供应链突变	固定后发生变化的工具定义或启动命令（按工具计算 SHA-256）。固定后发生变化的插件技能、命令、子 Agent、CLAUDE.md 和钩子（同一版本下修改文件的插件会被标记为 high）。每次会话启动时自动重新检查
能力与评分	按工具分类（执行、删除、写入、外传），未认证的远程写入权限，每个服务器的 0–100 分和 A–F 等级，以及建议的权限规则
供应链	OSV 漏洞和恶意版本、typosquat、缺失或刚发布的包、安装脚本、发布者变更（可选的网络检查）
运行时	每次 MCP 调用时运行钩子：在发送凭据前询问、在输出中发现注入指令或凭据时发出警告、记录不含内容的审计日志
策略	.mcp-security.json 中获准／被阻止的服务器和主机，并在审计、CI 和会话启动时强制执行
有害流向	服务器单独或协同持有“致命三要素”的全部三个环节（不可信输入、私有数据、外传能力）。这是一条安全态势说明（low 或 info），并非缺陷
Agent 上下文	技能及其脚本、斜杠命令、子 Agent、规则、CLAUDE.md 和插件钩子：指令覆盖、“不要告诉用户”、不可见文本、面向模型的 HTML 注释、读取凭据文件的指令、上传凭据的命令、下载并运行、编码执行、信息窃取脚本、预先批准且不受限制的 Bash
配置	env／标头／参数／URL 中的明文机密、纯 HTTP 远程服务、未固定的 npx／uvx 包、特权或未固定的 Docker 镜像、通过管道传给 shell 的启动方式、不同作用域间的重复名称

所有操作都在本地运行。除非你选择启用，否则不会向任何地方发送数据。

---

OWASP MCP Top 10 覆盖范围

每项发现都会在报告和 SARIF 中标记其对应的 OWASP MCP Top 10 ID。

ID	风险	覆盖范围
MCP01	令牌管理不当与机密泄露	✅ 检测环境变量、标头、参数和 URL 中的明文机密。在运行时，会在凭据发送到 MCP 服务前征求确认，并在收到凭据时发出警告
MCP02	权限范围扩大导致权限升级	✅ 能力清单（执行、删除、写入、数据外传），可直接粘贴的 permissions.ask 规则，以及特权容器或挂载范围过广的容器
MCP03	工具投毒	✅ 检测到 26/27 种已发布技术，包括完整架构投毒、影子工具和名称冲突，以及 rug-pull 固定版本
MCP04	供应链攻击	✅ 未固定版本的包、镜像和 Git 源；OSV 漏洞和恶意版本；仿冒包；新包；安装脚本；发布者变更
MCP05	命令注入与执行	✅ 标记可执行命令的工具；adversarial_test 可在你拥有的服务中查找可注入参数
MCP06	通过上下文载荷进行提示词注入	✅ 检测工具元数据中的此类内容，并在运行时检测工具输出中的此类内容（英文模式）
MCP07	身份验证/授权不足	✅ 使用纯 HTTP 的远程服务；未经身份验证却暴露写入或执行工具的远程服务；OAuth 检测
MCP08	缺少审计与遥测	✅ 记录每次 MCP 调用的本地审计日志，不包含内容，并提供 query_audit_log
MCP09	影子 MCP 服务	✅ 在用户、项目、本地、插件和 Claude Desktop 配置中进行发现；在审计、CI 和会话开始时强制执行已批准服务策略
MCP10	上下文注入与过度共享	✅ 检测对话和系统提示词采集、Markdown 图片数据外传、输出中的凭据，以及网络数据外传清单

本地工具无法执行的操作（计划纳入托管版 Team 计划）：组织范围内的发现与审计汇总、OAuth 作用域审查。

---

快速演示（1 分钟）

尝试离线对比合成示例，无需依赖项、账户或 API 密钥：

git clone https://github.com/petrovicistefan/mcp-security-guard.git
cd mcp-security-guard
node scripts/offline-demo.mjs

演示会检查两段已保存的工具描述：一段会产生指令覆盖和敏感路径相关发现；另一段干净的描述不会产生任何发现。自行运行扫描并生成 HTML 报告。

---

工具

工具	网络	启动	描述
list_mcp_servers	❌	❌	列出为此项目配置的所有 MCP 服务（Claude Code 中用户、本地和项目范围的配置，以及 Claude Desktop），并注明其传输方式。只读；不会启动任何内容。
audit_mcp_config	❌	❌	对 MCP 服务配置进行静态审计：检查 env/headers/args/URLs 中的明文密钥、使用明文 HTTP 的远程服务、未锁定版本的 npx/uvx 包、未锁定版本或具有特权的 Docker 容器、通过管道传递给 shell 的启动命令，以及重复的服务名称。只读；不会启动任何内容。
audit_server_tools	❌	✅ 确认	连接到所选 MCP 服务，列出其工具，并检查每个工具的名称、描述和架构是否存在工具投毒、跨服务工具遮蔽和突然替换。绝不调用被扫描的工具。需要 confirm_launch: true。
pin_tools	❌	✅ 确认	将每个工具定义的 SHA-256 哈希记录到 ~/.claude/mcp-security/pins.json，用于检测突然替换。仅在审查完审计结果后固定。需要 confirm_launch: true。
audit_agent_context	❌	❌	扫描 CLAUDE.md、技能、斜杠命令、子 Agent、规则和插件钩子，检查指令覆盖、要求向用户隐瞒内容、不可见文本、凭据外传和编码执行。只读；不会启动任何内容。
pin_context	❌	❌	将每个技能、命令、子 Agent、规则、CLAUDE.md 和插件钩子配置的 SHA-256 记录到 ~/.claude/mcp-security/context-pins.json，用于检测插件中的突然替换。仅在审查完审计结果后固定。
analyze_tool_definitions	❌	❌	离线分析你提供的工具定义（例如，你正在开发的服务返回的 tools/list 输出）。适用于 CI 或发布前检查。绝不会连接任何内容。
check_supply_chain	✅ 确认	❌	对于 npx/uvx 服务，检查 npm/PyPI 包和 OSV 数据库：漏洞、恶意版本、仿冒包、安装脚本、弃用情况和发布者变更。仅发送包名称和版本。需要 confirm_network: true。
apply_fixes	有条件	有条件	修复项目文件中的发现项：添加 permissions.ask 规则（需要 confirm_launch）、固定未锁定版本的包（需要 confirm_network），或将明文密钥替换为 ${VAR} 引用。默认以试运行模式执行；写入前会备份文件。
security_dashboard	❌	有条件	打开交互式仪表板，显示评分、等级、按严重程度分类的发现项、OWASP MCP Top 10 细分结果和固定按钮。scan="config" 为只读；scan="full" 需要 confirm_launch: true。MCP App 宿主会以内嵌方式呈现。
generate_policy	❌	❌	返回一个 .mcp-security.json 策略，其中仅批准当前配置的服务。将其提交到版本控制，可在 CI 和审计中标记影子服务。只读；不会写入文件。
team_status	✅ 确认	❌	从团队后端同步组织策略，并显示组织名称、角色、策略版本和集群报告状态。需要团队 API 密钥和 confirm_network: true。
request_approval	✅ 确认	❌	当团队策略要求审批时，为被阻止的服务或插件创建审批请求。由管理员通过 CLI 决定。需要 confirm_network: true。
team_report	✅ 确认	❌	显示集群报告将发送的内容（服务/插件名称、版本、传输方式；绝不包含路径、参数、环境变量或密钥）。使用 confirm_send: true 时，若管理员已启用集群可见性，则会发送报告。
export_bom	❌	❌	Agent 物料清单：列出 MCP 服务、插件、技能、命令、子 Agent、CLAUDE.md 和钩子，并包含 SHA-256、固定状态、评分和 OWASP 证据。输出 CycloneDX 1.6 JSON 或 Markdown 摘要。静态；不会启动任何内容。
query_audit_log	❌	❌	汇总本地运行时审计日志：按服务/工具统计 MCP 工具调用，以及发送/返回凭据或输出中包含注入指令的调用。日志仅存储哈希和大小，绝不存储参数或输出。
adversarial_test	❌	✅ 确认	使用命令注入和路径遍历载荷调用工具，以查找存在漏洞的参数。仅用于你拥有或运营的服务。需要 i_own_this_server: true 和 confirm_launch: true。默认跳过破坏性工具。

---

CI / GitHub Action

如果拉取请求向 .mcp.json 添加了有风险的 MCP 服务，则使其失败，并在 GitHub 代码扫描中显示发现项：

name: MCP security
on: [pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: petrovicistefan/mcp-security-guard@main
        id: mcp
        with:
          fail-on: high          # critical | high | medium | low | info | none
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: ${{ steps.mcp.outputs.sarif-file }}

若还要使添加了投毒技能、命令或 CLAUDE.md 的拉取请求失败，请设置 context: true（第二个 SARIF 文件位于 context-sarif-file）。

命令行：

# Audit project-level MCP servers
npx mcp-security-guard audit --project-only --format sarif --output mcp.sarif

# For MCP server authors: analyze a saved tools/list result
npx mcp-security-guard analyze-tools tools.json --name my-server

# Scan skills, commands, subagents and CLAUDE.md
npx mcp-security-guard audit-context --project-only --fail-on high

# Pin what you've reviewed
npx mcp-security-guard pin-context

# Scan a server before installing it
npx mcp-security-guard scan server-config.json --confirm-launch

# Test your own server for command injection (calls tools)
npx mcp-security-guard adversarial my-server.mcp.json --server my-server --i-own-this-server --confirm-launch

# Fix what the audit found
npx mcp-security-guard fix --pin-versions            # npx pkg → [email protected]
npx mcp-security-guard fix --env-refs --write        # secrets → ${VAR} references
npx mcp-security-guard fix --permissions --confirm-launch --write

# Generate a team policy from current configuration
npx mcp-security-guard policy-init && git add .mcp-security.json

输出格式： --format markdown|json|sarif|html（HTML 是独立的报告文件）。

退出代码： 0 表示无问题，1 表示发现项达到或超过 --fail-on，2 表示用法错误。

---

交互式仪表板

security_dashboard 是一个 MCP App，用于托管支持 MCP Apps 的客户端（Claude Desktop、claude.ai、VS Code Copilot），并以内嵌方式呈现。

它会显示每个服务的分数和等级、可按严重程度和服务筛选的发现项、OWASP MCP Top 10 分类、建议的权限规则，以及 Full scan 和 Pin 按钮。

在 Claude Desktop 中使用：

{
  "mcpServers": {
    "mcp-security-guard": {
      "command": "node",
      "args": ["/path/to/mcp-security-guard/plugin/dist/index.mjs"]
    }
  }
}

让 Claude “打开 MCP 安全仪表板”。

在本地开发：npm run dashboard:dev -- /path/to/project

---

运行时钩子

钩子	功能	设置
PreToolUse on mcp__*	当参数中包含凭据时请求确认	MCP_SECURITY_SECRET_GUARD=ask（默认）、deny 或 off
PostToolUse on mcp__*	当输出包含注入指令、隐藏字符、数据外泄标记或凭据时发出警告	始终启用
审计日志	~/.claude/mcp-security/audit.jsonl：服务、工具、时间、输入哈希和大小。不记录参数或输出。达到 10 MB 后轮换	设置 MCP_SECURITY_AUDIT_LOG=off 可禁用

每次 MCP 调用的钩子会增加约 40 ms 的耗时。

会话启动检查会重新验证已固定的服务，除非发生变化，否则不会显示提示：

• MCP_SECURITY_SESSION_CHECK=full（默认）：比较配置并重新列出工具
• MCP_SECURITY_SESSION_CHECK=config：仅比较配置，不启动任何内容
• MCP_SECURITY_SESSION_CHECK=off：禁用

---

团队方案（付费，可选）

目前团队密钥需手动发放：联系我。

使用团队 API 密钥（MCP_SECURITY_API_KEY 或插件密钥设置）后，你可以使用：

• 集中策略：由管理员推送，并与用户/项目策略一同强制执行（仓库无法放宽该策略）
• 已批准的插件（allowedPlugins、blockedPlugins）：在审计、CI 和会话启动时强制执行
• 集群清单（需选择加入并同意）：名称、版本、作用域、传输方式、包/主机名——绝不收集路径、参数、环境变量或密钥
• 审批流程：team request、team approve、兼容 Slack 的 Webhook 警报
• 密钥和席位：管理员可创建/撤销每位开发者的密钥；购买可设置席位上限
• Web 仪表板，位于 /v1/team/dashboard：集群、审批、策略、密钥、设置
• 电子邮件警报（每个组织每小时最多 20 封），并支持 Webhook
• 合规证据：team compliance 会生成 Markdown 报告，包含 OWASP MCP Top 10 控制项、证据、违规情况和待审批事项

管理员操作仅限命令行（不是 MCP 工具），因此注入文本无法触发这些操作。

mcp-security-guard team status
mcp-security-guard team report --dry-run
mcp-security-guard team request plugin some-plugin --note "for docs site"
mcp-security-guard team approvals --status pending      # admin
mcp-security-guard team approve apr_… --note ok         # admin
mcp-security-guard team policy-push policy.json         # admin
mcp-security-guard team keys create ana                 # admin
mcp-security-guard team settings --fleet on --webhook https://hooks.slack.com/… --email [email protected]

以上所有功能均保持免费。免费插件功能完整。有关发送内容，请参阅 PRIVACY.md。

---

基准测试结果

**测量结果：**在公开记录的技术样本集中检测出 26/27 项攻击，在 13 个高难度良性样本和 17 个真实服务（83 个工具）中 误报数为 0。

覆盖的技术：工具投毒和 <IMPORTANT> 标签（Invariant Labs）、行跳跃和 ANSI 转义欺骗（Trail of Bits）、完整架构投毒（CyberArk）、工具影射、名称冲突、零宽字符/Unicode 标签/双向文本隐写、形似字符名称、base64 载荷、HTML 注释、通过 URL/参数/Markdown 图片进行数据外泄。

完整的方法和结果请参阅 bench/RESULTS.md。

---

开发

npm install
npm run build      # bundles to plugin/dist/ (committed, so plugin runs without npm install)
npm test
npm run bench      # false-positive gate on real servers (network; Docker images optional)

test/fixtures/poisoned-server.mjs 是端到端测试中使用的恶意服务。

---

贡献

欢迎提交小型且可复现的贡献：良性回归样本、合成检测案例、客户端配置测试，以及更清晰的示例。

请参阅 CONTRIBUTING.md 了解指南。

贡献指南 · 待办事项 · 报告误报

---

安全与隐私

• 发现漏洞？ 请参阅 SECURITY.md
• 读取、写入和发送的内容： PRIVACY.md
• 变更： CHANGELOG.md

信任模型：

• 只读（固定文件、审计日志和 policy-init 除外）
• 仅在明确选择启用时联网
• 所有输出中的机密均会隐藏
• 静态检查可降低风险，但无法证明服务安全

---

许可证

MIT 许可证

Copyright (c) 2026 Stefan Petrovici

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和／或销售本软件副本的权利，并允许向获得本软件的人提供本软件，前提是符合以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

本软件按“原样”提供，不附带任何明示或默示的保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对因本软件或本软件的使用或其他处理而引起或与之相关的任何索赔、损害或其他责任负责，无论是合同诉讼、侵权行为还是其他诉讼。

完整的许可证文本请参阅 LICENSE。

---

限制

需要 OAuth 的远程服务（大多数托管 MCP 服务）无法在工具层级进行扫描：扫描器无法重复使用 Claude Code 的令牌。不过，仍会审计其配置。

---

关于作者

我是 Stefan Petrovici：热爱 IT，是一位丈夫和父亲。我独自开发了 MCP Security Guard。我正在找工作。

我负责端到端构建 Web 应用——前端、后端、API 和部署，也乐于参与其他需要构建的项目。这个代码库展示了我的工作方式：测试、CI、严谨的文档和对安全的重视。

我也开发 WordPress 和 WooCommerce 插件，可在 pluginsforstores.com 获取。

如果贵团队正在招聘，请通过 [email protected] 联系我。

---

⭐ 支持这个项目

觉得它有用？为这个代码库点星！

GitHub 星标有助于其他开发者发现这个项目，也能让你稍后再找到它。感谢你支持开源！

---

MCP Security Guard 与 Anthropic、Snyk、Cisco 或本文档中提到的任何其他安全厂商均无关联。