pyobfus — Python Obfuscator

pyobfus-mcp — pyobfus 的 Model Context Protocol 服务

pyobfus-mcp 将 pyobfus — Python 混淆器 — 提供给任何支持 MCP 的 AI 编码 Agent：Claude Desktop、Claude Code、Cursor、GitHub Copilot、Windsurf、Zed、Codex、CodeBuddy，以及其他任何支持 Model Context Protocol 的产品。

配置完成后，你可以这样说：

“检查这个 FastAPI 项目是否适合混淆，然后为它生成 pyobfus.yaml。”

Agent 会自主调用 check_obfuscation_risks 和 generate_pyobfus_config — 无需复制粘贴 CLI 命令，也无需手动编辑配置。

提供的工具

0.3.16 版本提供 9 个工具：7 个 Community 工具和 2 个层级／试用指导工具。

工具	功能
protect_project(path, output_dir?, preset?, verify?, verify_cmd?, save_mapping?)	一次调用即可完成并自验证的工作流。 扫描风险，选择适配框架的预设，执行混淆，然后在隔离的子进程中进行字节码编译和导入冒烟测试，并返回 verified: true/false（以及 confidence）。verified 表示通过了编译和导入冒烟测试；如果你提供了 verify_cmd，也会运行该命令；这并不意味着已经测试过应用的行为。会在输出目录旁边（绝不会放在其中）写入私有的反混淆映射。用户想要“发布前保护／混淆”并期待看到成功标记，而不只是进行转换时，请使用此工具。
check_obfuscation_risks(path, verify_dependencies_online=false, use_project_config=true)	考虑配置的预检扫描，检查 eval／exec、动态属性访问和框架反射。将 use_project_config=false 设为传统的无配置扫描。将 verify_dependencies_online=true 设为启用对公共 PyPI 依赖名称的验证；默认仍不允许出站网络访问。返回严重级别计数、检测到的框架和建议的预设。
generate_pyobfus_config(path, preset_override?, write?)	自动检测框架 → 生成 pyobfus.yaml。默认返回 YAML 文本而不写入文件；write=True 会将其保存到磁盘。
unmap_stack_trace(trace, mapping_path)	使用 mapping.json 还原生产环境堆栈跟踪中的混淆标识符。
check_delivery(path, build_report?, provenance_manifest?)	发布前，检查输出目录或 .whl 中是否包含映射文件、私钥或原始源代码，以及构建未生成的文件。只读；需要 pyobfus >=0.7.1；较旧的 Core 会返回 FeatureUnavailable。
list_presets()	列出所有预设（community／适配框架／Pro）。
explain_preset(name)	说明指定预设会更改哪些内容：排除项、文档字符串处理和参数保留。
recommend_tier(path)	分析项目并推荐使用 community 还是 Pro，同时说明原因并给出具体的后续命令。
start_pro_trial()	提供结构化指导，说明如何开始 5 天 Pro 试用。

所有工具都会返回包含 status 字段、自由文本 ai_hint 和机器可读 next_tool 字段（{tool, reason, args}）的字典，方便 Agent 按确定顺序串联步骤。protect_project 中的 verify_cmd 会执行任意命令，因此默认关闭；只有设置 PYOBFUS_MCP_ALLOW_VERIFY_CMD=1 才会启用。

安装

零安装（推荐）

如果你安装了 uv，无需单独安装 — 将客户端指向 uvx 即可；它会在首次运行时将 pyobfus-mcp（以及 pyobfus 和 MCP SDK）下载到临时环境中。无需 API 密钥。

{
  "mcpServers": {
    "pyobfus": {
      "command": "uvx",
      "args": ["pyobfus-mcp"]
    }
  }
}

或者使用 pip 安装

pip install pyobfus-mcp

这会自动安装 pyobfus 和 MCP Python SDK。然后在下方各客户端的配置中使用 "command": "pyobfus-mcp"。

配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "pyobfus": {
      "command": "pyobfus-mcp"
    }
  }
}

重启 Claude Desktop。pyobfus 工具将显示在工具列表中。

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "pyobfus": {
      "command": "pyobfus-mcp"
    }
  }
}

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "pyobfus": {
      "command": "pyobfus-mcp"
    }
  }
}

Zed

在 ~/.config/zed/settings.json 中：

{
  "context_servers": {
    "pyobfus": {
      "command": {
        "path": "pyobfus-mcp",
        "args": []
      }
    }
  }
}

Claude Code

claude mcp add pyobfus pyobfus-mcp

示例会话

User:  Can you check whether this Python project is safe to obfuscate?
       Path: /Users/me/code/my-api

Agent: [invokes check_obfuscation_risks("/Users/me/code/my-api")]
       I found 2 high-severity and 3 medium-severity patterns. FastAPI is
       detected, so I'd suggest the `fastapi` preset. Want me to generate
       the config?

User:  Yes please, write it.

Agent: [invokes generate_pyobfus_config("/Users/me/code/my-api",
         preset_override="fastapi", write=True)]
       Wrote pyobfus.yaml. Next: pyobfus /Users/me/code/my-api -o dist/
       -c pyobfus.yaml

使用 AI 助手调试混淆后的代码

杀手级功能：即使代码经过混淆，也能继续使用 AI 辅助调试。

User:  Here's a crash from prod. Can you help?
       [pastes traceback full of I0, I1, I2...]

Agent: [invokes unmap_stack_trace(trace, "path/to/mapping.json")]
       Reversed. The crash is in Calculator.add() called from
       main() — 'Calculator' object has no attribute 'add_x'. Looks like
       a typo in the method call site…

验证工具完整性

工具投毒／“rug-pulls”——服务的工具描述在你审查并信任它们之后悄然发生变化——是 2026 年 MCP 安全基线中的头号威胁。pyobfus-mcp-verify 会将当前安装的软件包中的工具描述／架构与发布时冻结的清单进行比对：

pyobfus-mcp-verify
# OK: tool descriptions match the shipped manifest (digest 5cf4c902d460...).

不匹配（退出代码为 1）意味着已安装的工具与该版本发布的内容不同——在信任此服务之前，值得进行调查。这是一种自洽性摘要，而非加密签名：它能证明软件包与其随附的清单相符，但不能证明特定方对其进行了签名。若要获得更强的保证，请将打印出的摘要与已安装版本对应的 GitHub Release 说明中发布的摘要进行比对。

独立安全扫描

已发布的 PyPI 软件包（而非本地构建版本）已通过 Cisco 的开源 mcp-scanner 扫描——先进行实时的 initialize → tools/list 握手，再对当时公开的八个工具进行 YARA 恶意软件特征码和依赖项漏洞分析。截至 pyobfus-mcp 0.3.6（2026-08-20）的结果：8/8 个工具安全，0 个发现项。完整的可复现命令、原始输出，以及对本次扫描覆盖范围和未覆盖范围的如实说明，请参阅： docs/MCP_SECURITY_SCAN.md。

许可证

Apache-2.0。与 pyobfus 主软件包相同。此服务提供 Community 工具和关于套餐等级／试用的说明；Pro 构建功能仍受许可证限制。

链接

• 主软件包：https://pypi.org/project/pyobfus/
• 源代码：https://github.com/zhurong2020/pyobfus
• 官方 MCP 注册表条目：https://registry.modelcontextprotocol.io/v0/servers?search=pyobfus
• AI 集成策略：docs/AI_INTEGRATION_STRATEGY.md
• MCP 规范：https://modelcontextprotocol.io/