STARWARCLOUD STARWAR.AI
返回市场
MCP扫描

MCP扫描

作者：invariantlabs-ai1286 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

<p align="center"> <h1 align="center"> mcp-scan </h1> </p> <p align="center"> 本地和远程MCP服务器的安全扫描工具 </p> <p align="center"> <a href="https://pypi.python.org/pypi/mcp-scan"><img src="https://img.shields.io/pypi/v/mcp-scan.svg" alt="mcp-scan"/></a> <a href="https://pypi.python.org/pypi/mcp-scan"><img src="https://img.shields.io/pypi/l/mcp-scan.svg" alt="mcp-scan license"/></a> <a href="https://pypi.python.org/pypi/mcp-scan"><img src="https://img.shields.io/pypi/pyversions/mcp-scan.svg" alt="mcp-scan python version requirements"/></a> </p> <div align="center"> <img src=".github/mcp-scan-cmd-banner.png?raw=true" alt="MCP-Scan logo"/> </div>

主要特点

  • 自动发现MCP配置
  • 检测MCP安全漏洞：
    • 提示注入攻击
    • 工具中毒攻击
    • 毒性流
  • 扫描本地STDIO MCP服务器
  • 扫描远程HTTP/SSE MCP服务器

快速开始

MCP服务器扫描

运行MCP扫描：

uvx mcp-scan@latest

这将扫描已安装的服务器中的工具、提示和资源的安全漏洞。它会自动发现多种MCP配置，包括Claude、Cursor和Windsurf。

要扫描特定的MCP服务器配置，例如VS Code MCP配置，可以运行：

mcp-scan ~/.vscode/mcp.json

示例运行

MCP扫描安全漏洞演示

MCP安全扫描器功能

MCP-Scan是一个安全扫描工具，用于静态和动态扫描及监控您的MCP连接。它检查它们是否存在常见的安全漏洞，如提示注入，工具中毒和毒性流。请参阅我们的详细文档以获取更多信息。

MCP-Scan主要在两种模式下操作，可以单独或联合使用：

  1. mcp-scan scan 静态扫描您已安装的所有服务器中的恶意工具描述和工具（例如工具中毒攻击，跨域升级，拉扯攻击，毒性流）。

    快速开始 →.

  2. mcp-scan proxy 实时连续监控您的MCP连接，并可以限制代理系统通过MCP能做什么（工具调用检查，数据流约束，PII检测，间接提示注入等）。

    快速开始 →.

<br/> <br/> <div align="center"> <img src="https://explorer.invariantlabs.ai/docs/mcp-scan/assets/proxy.svg" width="420pt" align="center"/> <br/> <br/>

mcp-scan 在代理模式下.

</div>

功能

  • 扫描Claude、Cursor、Windsurf和其他基于文件的MCP客户端配置
  • 使用Guardrails扫描工具中的提示注入攻击和工具中毒攻击
  • 对MCP工具调用和响应实施护栏策略，包括PII检测，秘密检测，工具限制以及完全自定义的护栏策略。
  • 通过mcp-scan proxy实时审计和记录MCP流量
  • 检测跨域升级攻击（例如工具阴影），并检测和防止MCP拉扯攻击，即mcp-scan通过哈希检测到MCP工具的变化

服务器代理

使用mcp-scan proxy，您可以监控、记录并保护机器上的所有MCP流量。这允许您检查代理和工具的运行时行为，并防止来自不可信来源（如网站或电子邮件）的攻击尝试利用您的代理。mcp-scan代理是一个后台运行的动态安全层，持续监控您的MCP流量。

示例运行

<img width="903" alt="image" src="https://gips3.baidu.com/it/u=3031097255,199720292&fm=3081&app=3081&f=PNG?w=1806&h=814" />

实施护栏

您还可以添加护栏规则，以限制并通过代理验证工具使用的序列。

为此，请创建一个~/.mcp-scan/guardrails_config.yml，内容如下：

<client-name>:  # 您客户端的简写（例如，cursor，claude，windsurf）
  <server-name>:  # 根据mcp配置的服务器名称（例如，whatsapp-mcp）
    guardrails:
      secrets: block # 阻止带有秘密的调用/结果

      custom_guardrails:
        - name: "过滤包含'error'的工具结果"
          id: "error_filter_guardrail"
          action: block # 或者只是'log'
          content: |
            raise "发现错误。" if:
              (msg: ToolOutput)
              "error" in msg.content

从那时起，所有通过mcp-scan proxy代理的调用都将根据您当前客户端/服务器的配置护栏规则进行检查。

自定义护栏是使用Invariant Guardrails实现的。要了解这些规则的更多信息，请参阅此游乐场环境和官方文档。

它是如何工作的

扫描

MCP-Scan scan搜索配置文件以查找MCP服务器配置。它连接到这些服务器并检索工具描述。

然后扫描工具描述，既进行本地检查，也通过API调用Invariant Guardrailing。为此，工具名称和描述与invariantlabs.ai共享。通过使用MCP-Scan，您同意invariantlabs.ai的使用条款和隐私政策。

Invariant Labs收集数据用于安全研究目的（仅关于工具描述及其随时间的变化，而不是您的用户数据）。如果您不想分享您的工具，请勿使用MCP-scan。此外，您的扫描会被分配一个唯一、持久且匿名的ID用于分析。您可以使用--opt-out标志选择不发送此信息。

MCP-scan不会存储或记录任何使用数据，即MCP工具调用的内容和结果。

代理

对于使用mcp-scan proxy的运行时监控，MCP-Scan可以用作代理服务器。这允许您实时监控和实施系统范围内的MCP流量护栏。为此，mcp-scan暂时将本地Invariant Gateway注入MCP服务器配置中，以拦截和分析流量。proxy命令退出后，Gateway将从配置中移除。

您还可以配置代理的护栏规则，以实时执行安全策略。这包括PII检测，秘密检测，工具限制以及自定义护栏策略。护栏和代理完全在本地使用Guardrails操作，不需要任何外部API调用。

CLI参数

MCP-scan提供以下命令：

mcp-scan - Model Context Protocol服务器和工具的安全扫描器

常用选项

这些选项适用于所有命令：

--storage-file FILE    存储扫描结果和白名单信息的路径（默认：~/.mcp-scan）
--base-url URL         验证服务器的基本URL
--verbose              启用详细的日志输出
--print-errors         显示错误详情和跟踪
--full-toxic-flows     显示所有可能参与毒性流的工具。默认只显示前三项。
--json                 输出结果为JSON格式而非富文本

命令

scan（默认）

扫描MCP配置中的工具、提示和资源的安全漏洞。

mcp-scan [CONFIG_FILE...]

选项：

--checks-per-server NUM       每个服务器要执行的检查数量（默认：1）
--server-timeout SECONDS      等待服务器连接超时的秒数（默认：10）
--suppress-mcpserver-io BOOL  抑制MCP服务器的stdout/stderr（默认：True）

proxy

运行代理服务器以实时监控和实施系统范围内的MCP流量护栏。暂时将Gateway注入MCP服务器配置中，以拦截和分析流量。proxy命令退出后，Gateway将再次被移除。

此命令需要proxy可选依赖项（额外）。

  • 通过uvx运行： 
    uvx --with "mcp-scan[proxy]" mcp-scan@latest proxy
    这将在uvx管理的虚拟环境中安装proxy额外项，而不是当前shell venv。

选项：

CONFIG_FILE...                  要设置代理的MCP配置文件路径。
--pretty oneline|compact|full   以不同格式美化输出（默认：compact）

inspect

打印工具、提示和资源的描述而不进行验证。

mcp-scan inspect [CONFIG_FILE...]

选项：

--server-timeout SECONDS      等待服务器连接超时的秒数（默认：10）
--suppress-mcpserver-io BOOL  抑制MCP服务器的stdout/stderr（默认：True）

whitelist

管理批准实体的白名单。如果没有提供参数，则此命令显示当前白名单。

# 查看白名单
mcp-scan whitelist

# 添加到白名单
mcp-scan whitelist TYPE NAME HASH

# 重置白名单
mcp-scan whitelist --reset

选项：

--reset                       重置整个白名单
--local-only                  仅更新本地白名单，不贡献到全局白名单

参数：

TYPE                          要白名单的实体类型："tool"，"prompt"或"resource"
NAME                          要白名单的实体名称
HASH                          要白名单的实体哈希

help

显示详细帮助信息和示例。

mcp-scan help

示例

# 扫描所有已知的MCP配置
mcp-scan

# 扫描特定配置文件
mcp-scan ~/custom/config.json

# 只检查工具而不验证
mcp-scan inspect

# 查看白名单工具
mcp-scan whitelist

# 将工具添加到白名单
mcp-scan whitelist tool "add" "a1b2c3..."

演示

此仓库包含一个易受攻击的MCP服务器，可以展示MCP-Scan找到的Model Context Protocol安全问题。

如何演示MCP安全问题？

  1. 克隆此仓库
  2. 在克隆的git仓库根目录创建一个mcp.json配置文件，内容如下：
{
  "mcpServers": {
    "Demo MCP Server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "mcp", "run", "demoserver/server.py"],
    }
  }
}
  1. 运行MCP-Scan：uvx --python 3.13 mcp-scan@latest scan --full-toxic-flows mcp.json

注意：如果将mcp.json配置文件路径放置在其他位置，则调整MCP服务器配置中的args路径，以反映MCP服务器（demoserver/server.py）的路径，以及运行MCP-Scan CLI的uvx命令的正确mcp.json文件路径。

MCP-Scan不再接受外部贡献

MCP-Scan目前无法再接受外部贡献。我们专注于稳定发布。 我们欢迎通过GitHub问题提交建议、错误报告或功能请求。

开发设置

要从此源运行此包，请遵循以下步骤：

uv run pip install -e .
uv run -m src.mcp_scan.cli

对于代理功能（例如，mcp-scan proxy，mcp-scan server），请使用代理额外项安装：

uv run pip install -e .[proxy]

在自己的项目/注册表中包含MCP-scan结果

如果您想在自己的项目或注册表中包含MCP-scan结果，请通过mcpscan@invariantlabs.ai联系团队，我们将为您提供帮助。 对于自动化扫描，我们建议使用--json标志并解析输出。

进一步阅读

更新日志

查看CHANGELOG.md。