mcpshield

一个针对未修补的 MCP STDIO 命令注入漏洞（CVE-2026-30623 系列，由 OX Security 于 2026 年 4 月披露，归为“设计问题”——无 SDK 补丁）的即插即用修复方案。只需导入一行代码，你的 Python 应用启动的每个 stdio MCP 服务器，在操作系统生成进程之前，其命令/参数/环境变量都会经过验证。

如果你是新手，请先阅读 适用范围，然后 安装 和 快速入门 将让你在两分钟内获得保护。

目录

• 项目状态
• 适用范围
• 安装
• 快速入门
  • 选项 A：自动补丁（Python MCP 主机）
  • 选项 B：静态检查（任何语言，零执行）
  • 选项 C：启动监控器（非 Python 主机）
• 哪些会被阻止，哪些会发出警告
• 逃生舱
• CLI 参考
• 已知限制
• 项目结构
• 开发

项目状态

Pre-1.0，正在积极开发中。

• 验证引擎、自动补丁和 CLI（check/launch/rules）已实现，并通过自动测试套件覆盖，测试针对测试机器上安装的真实二进制文件（python、node、npx）运行，而非模拟——包括通过真实生成的服务器夹具进行的端到端 MCP 握手，以及对 launch 进行的真实子进程级测试。
• 尚未发布到 PyPI——参见 安装。
• 关于涵盖与未涵盖的内容，请参见 SECURITY.md。

适用范围

适用范围： 在 stdio MCP 服务器启动到达操作系统进程生成层之前，验证其命令 + 参数 + 环境变量，具体目的是关闭 SECURITY.md 中描述的命令/参数注入路径。

明确排除： 扫描服务器已声明的工具以检查高风险功能（这是另一个问题——请参见 AgentGuard）、对生成进程进行沙箱处理，以及非 stdio（SSE/HTTP）MCP 传输。

安装

git clone <本仓库>
cd mcpshield
pip install -e .          # 核心 CLI：仅需 click + rich
pip install -e ".[mcp]"   # 如需 Python 自动补丁（需要 `mcp` SDK）

验证安装成功：

mcpshield --version
mcpshield --help

快速入门

选项 A：自动补丁（Python MCP 主机）

如果你的应用是用 Python 编写的，并且自己构建了 StdioServerParameters / 调用了 mcp.client.stdio.stdio_client，请在入口文件的最顶部添加一个导入——在所有其他模块导入 mcp.client.stdio 之前：

import mcpshield.autopatch  # 副作用导入；必须放在最前面

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
# ... 像以前一样使用 stdio_client —— 现在它已经过验证了

不安全的启动现在会引发 mcpshield.core.errors.UnsafeConfigurationError（ValueError 的子类），而不会启动任何进程。

选项 B：静态检查（任何语言，零执行）

审计一个 mcpServers 风格的配置文件，无需运行任何东西：

mcpshield check claude_desktop_config.json

+---------------------------------------------------------------+
| Server           | Status  | Command | Detail                 |
|------------------+---------+---------+------------------------|
| filesystem       | OK      | npx     | -                      |
| evil-server      | BLOCKED | npx     | 参数 '...' 包含        |
|                  |         |         |  shell 元字符          |
+---------------------------------------------------------------+

  1 个通过，0 个警告，1 个阻止

如果任何服务器被 BLOCKED，则退出码非零（添加 --strict 也会在 WARN 时失败）——可直接放入 CI 中。

选项 C：启动监控器（非 Python 主机）

对于无法使用 Python 自动补丁的 MCP 客户端（Node、Java、Rust 等），将其配置指向 mcpshield 而不是实际命令：

{
  "command": "mcpshield",
  "args": ["launch", "--", "npx", "-y", "some-mcp-server"]
}

launch 会进行验证，然后通过相同的 stdio 执行实际命令（透明透传）——如果启动不安全，则会以明确的错误信息拒绝。

哪些会被阻止，哪些会发出警告

原生二进制文件的参数检查更宽松，因为它们直接 exec——没有 shell 重新解析参数列表。可被 shell 解释的命令（最常见的是 Windows 上的 npx.cmd/npx.bat）会接受严格检查，因为这是底层 CVE 利用的确切机制。

逃生舱

两者都是故意的、按值选择的 opt-in——绝非全局“禁用检查”标志：

• allow_raw_args=["--some-value-with-a-pipe"]（库）豁免你已审查并信任的特定参数值。
• allow_env=["SOME_VAR"] 允许通常被剥离的环境变量原样通过。

CLI 参考

已知限制

• 尚未发布到 PyPI——安装需要 git clone。
• 自动补丁仅修补在修补时查找到的 mcp.client.stdio.stdio_client。如果在 import mcpshield.autopatch 之前已经通过 from mcp.client.stdio import stdio_client 持有引用的代码会绕过补丁——请始终首先导入 mcpshield.autopatch。
• Shell 元字符检查基于拒绝列表，仅在解析的命令被检测为可被 shell 解释时应用。它不是完整的 shell 语法解析器——准确的范围边界请参见 SECURITY.md。
• check 使用运行它的机器来解析命令。如果配置在实际部署的机器上（不同的 PATH、不同的已安装工具）解析结果不同，则报告可能不同。

项目结构

mcpshield/
  autopatch.py           # 一行导入的修复，适用于 Python MCP 主机
  core/
    validate.py           # 验证引擎（命令/参数/环境变量检查）
    rules.py               # 阻止列表/允许列表数据
    errors.py               # UnsafeConfigurationError
  cli/
    main.py
    commands/ (check.py, launch.py, rules.py)
tests/
  fixtures/                 # 真实的良性 MCP 服务器 + 示例/恶意配置

开发

pip install -e ".[dev,mcp]"
pytest

测试套件针对运行该套件的机器上安装的实际 python/node/npx 二进制文件进行验证（解析方式与引擎自身解析相同），并包含通过真实生成的服务器夹具进行的端到端 MCP 握手——而非模拟。