pyobfus-mcp — Model Context Protocol server for pyobfus
pyobfus-mcp exposes pyobfus — the Python obfuscator — to any MCP-capable AI coding agent: Claude Desktop, Claude Code, Cursor, GitHub Copilot, Windsurf, Zed, Codex, CodeBuddy, and anything else that speaks the Model Context Protocol.
Once configured, you can say:
"Check if this FastAPI project is safe to obfuscate, then generate a pyobfus.yaml for it."
and the agent will autonomously call check_obfuscation_risks and generate_pyobfus_config — no copy/paste of CLI commands, no manual config editing.
| Tool | What it does |
|---|
protect_project(path, output_dir?, preset?, verify?, verify_cmd?, save_mapping?) | One-call, self-verifying pipeline. Scans risks, picks a framework-aware preset, obfuscates, then byte-compiles and import-smoke-tests the output in isolated subprocesses and returns verified: true/false (+ confidence). Writes a private de-obfuscation mapping alongside (never inside) the output. Reach for this when the user wants to "protect/obfuscate before shipping" and expects a green check, not just a transform. |
check_obfuscation_risks(path, verify_dependencies_online=false, use_project_config=true) | Config-aware pre-flight scan for eval/exec, dynamic attribute access, and framework reflection. Set use_project_config=false for the legacy config-free scan. Opt into public-PyPI dependency-name verification with verify_dependencies_online=true; outbound network access remains off by default. Returns severity counts, detected frameworks, and a suggested preset. |
generate_pyobfus_config(path, preset_override?, write?) | Auto-detect framework → generate pyobfus.yaml. Returns the YAML text without writing by default; write=True persists to disk. |
unmap_stack_trace(trace, mapping_path) | Reverse obfuscated identifiers in a production stack trace using a mapping.json. |
list_presets() | Enumerate every preset (community / framework-aware / Pro). |
explain_preset(name) | Describe what a named preset changes: exclusions, docstring handling, parameter preservation. |
recommend_tier(path) | Analyze a project and recommend community vs Pro, with reasoning and concrete next-step commands. |
start_pro_trial() | Return structured guidance for starting the 5-day Pro trial. |
All tools return dicts with a status field, a free-text ai_hint, and a machine-readable next_tool field ({tool, reason, args}) so an agent can chain steps deterministically. verify_cmd in protect_project runs an arbitrary command and is therefore opt-in behind PYOBFUS_MCP_ALLOW_VERIFY_CMD=1.
Install
Zero-install (recommended)
If you have uv, no separate install step is needed — point your client at uvx and it fetches pyobfus-mcp (plus pyobfus and the MCP SDK) into an ephemeral environment on first run. No API key required.
{
"mcpServers": {
"pyobfus": {
"command": "uvx",
"args": ["pyobfus-mcp"]
}
}
}
Or install with pip
This pulls pyobfus and the MCP Python SDK automatically. Then use "command": "pyobfus-mcp" in the per-client configs below.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"pyobfus": {
"command": "pyobfus-mcp"
}
}
}
Restart Claude Desktop. The pyobfus tools appear in the tool list.
Cursor
Edit ~/.cursor/mcp.json:
{
"mcpServers": {
"pyobfus": {
"command": "pyobfus-mcp"
}
}
}
Windsurf
Edit ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"pyobfus": {
"command": "pyobfus-mcp"
}
}
}
Zed
In ~/.config/zed/settings.json:
{
"context_servers": {
"pyobfus": {
"command": {
"path": "pyobfus-mcp",
"args": []
}
}
}
}
Claude Code
claude mcp add pyobfus pyobfus-mcp
Example session
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
Debugging obfuscated code with your AI assistant
The killer feature: keep AI-assisted debugging even after you obfuscate.
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…
Tool poisoning / "rug-pulls" — a server's tool descriptions silently
changing after you've reviewed and trusted them — are the #1 threat in
the 2026 MCP security baseline. pyobfus-mcp-verify checks the
currently-installed package's tool descriptions/schemas against a
manifest frozen at release time:
A mismatch (exit code 1) means the installed tools differ from what the
release shipped — worth investigating before trusting the server. This
is a self-consistency digest, not a cryptographic signature: it proves
the package matches its own shipped manifest, not that a specific party
signed it. For stronger assurance, compare the printed digest against
the one published in the GitHub Release notes
for the version you installed.
Independent security scan
The published PyPI package (not a local build) has been scanned with
Cisco's open-source mcp-scanner
— a live initialize → tools/list handshake followed by YARA
malware-signature and dependency-vulnerability analysis against all 8
exposed tools. Result as of pyobfus-mcp 0.3.6 (2026-08-20): 8/8 tools
SAFE, 0 findings. Full reproducible command, raw output, and an honest
statement of what this scan does and doesn't cover:
docs/MCP_SECURITY_SCAN.md.
License
Apache-2.0. Same as the main pyobfus package. The pyobfus Pro features remain license-gated; this MCP server only wraps the community-tier tools.
Links