pyobfus-mcp

io.github.zhurong2020Published by GitHub account zhurong2020v0.3.17Updated Oct 30, 2026

9 local Python protection tools, delivery checks and traceback reverse mapping. No telemetry.

VerifiedSTDIODesktop onlyDeveloper Tools Security & Monitoring

Server details

Identifier: io.github.zhurong2020/pyobfus-mcp
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account zhurong2020 for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.zhurong2020%2Fpyobfus-mcp.svg)](https://sourceweft.com/mcp/io.github.zhurong2020%2Fpyobfus-mcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Local MCP server that lets an AI coding agent scan, obfuscate and verify Python projects with pyobfus, check delivery output, and reverse obfuscated stack…

What you can do: Scan a Python project for obfuscation risks, detected frameworks and a suggested preset
Generate a pyobfus.yaml config, or run a one-call protect pipeline that obfuscates, byte-compiles and import-smoke-tests the output
List and explain presets, and recommend a community or Pro tier with next-step commands
Check an output directory or wheel before shipping for mapping files, private keys or original sources
Reverse obfuscated identifiers in a stack trace using a saved mapping file
Return structured guidance for starting the Pro trial
When to use it: Useful when you ship Python code and want an assistant to prepare and run obfuscation, confirm the protected build still imports, and keep debugging possible by unmapping production tracebacks. Also handy for pre-release checks that no mapping file or key leaks into a delivery artifact.
Requirements: Runs locally over stdio as a PyPI package (pyobfus-mcp), either via uvx with no separate install or via pip; pulls in pyobfus and the MCP Python SDK. No API key or environment variables are required. Outbound network access is off by default and only used if dependency verification is opted into. The delivery check needs pyobfus 0.7.1 or newer.

Before you install

protect_project writes obfuscated output and a private de-obfuscation mapping next to it; generate_pyobfus_config writes pyobfus.yaml only when write is set. verify_cmd runs an arbitrary command and is gated behind PYOBFUS_MCP_ALLOW_VERIFY_CMD. The trial tool only returns guidance and does not start the trial or purchase anything; Pro presets reference a checkout URL and price. A verified result covers compilation and an import smoke test, not application behaviour.

Installation

In SourceWeft

Open pyobfus-mcp in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

Tools exposed

Version 0.3.17 exposes 9 tools: 7 Community tools and 2 tier/trial guidance tools.

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`). `verified` covers compilation and an import smoke test, plus `verify_cmd` if you pass one; it does not mean your application's behaviour was tested. 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`.
`check_delivery(path, build_report?, provenance_manifest?)`	Before shipping, check an output directory or `.whl` for a mapping file, a private key or an original source, and for files the build did not produce. Read-only; requires pyobfus >=0.7.1; older Core returns `FeatureUnavailable`.
`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.

Or install with pip

This pulls pyobfus and the MCP Python SDK automatically. Then use "command": "pyobfus-mcp" in the per-client configs below.

Configure

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Restart Claude Desktop. The pyobfus tools appear in the tool list.

Cursor

Edit ~/.cursor/mcp.json:

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

Zed

In ~/.config/zed/settings.json:

json

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

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

Claude Code

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

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…

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…

Verifying tool integrity

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 the eight tools exposed at that time. 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 server exposes Community tools and tier/trial guidance; Pro build features remain licence-gated.

Tools

protect_project

One call to protect a Python project end-to-end AND verify it still works: scans risks, picks a framework-aware preset, obfuscates, then byte-compiles + import-smoke-tests the output in isolated subprocesses and returns verified:true/false. Writes a private de-obfuscation mapping alongside (not inside) the output. Use this when the user wants to 'protect/obfuscate before shipping' and expects a green check, not just a transform.

Parameterspathrequiredpresetverifytimeoutoutput_dirverify_cmdsave_mappingtrace_marker

check_obfuscation_risks

Scan a Python project for patterns that may break obfuscation (eval/exec, dynamic attribute access, framework reflection, unsafe model loading). Returns severity counts, detected frameworks (FastAPI/Django/Flask/Pydantic/Click/SQLAlchemy/ML), and a suggested preset. Also locates requirements*.txt / pyproject.toml and, only if verify_dependencies_online=true, checks each declared dependency against public PyPI to flag AI-hallucinated ('slopsquatting') package names -- off by default, this tool makes no outbound network calls unless you opt in. By default the scan honors the project's pyobfus config; set use_project_config=false for the legacy config-free scan.

Parameterspathrequireduse_project_configverify_dependencies_online

generate_pyobfus_config

Generate a pyobfus.yaml for a Python project. Auto-detects frameworks and applies the matching preset. By default returns the YAML text without writing to disk; set write=true to persist.

Parameterspathrequiredwritepreset_override

unmap_stack_trace

Reverse obfuscated identifiers in a stack trace using a pyobfus mapping.json. Accepts the trace as plain text and the path to a mapping file produced by --save-mapping.

Parameterstracerequiredmapping_pathrequired

check_delivery

Check an output directory or .whl right before shipping: fails on a pyobfus mapping file, a private key or an original source file inside it, and warns about Python files the build did not produce or Pro options the build skipped. Pass the build's --build-report and --provenance-manifest JSON for the full check. Read-only: files are hashed, never imported or executed, and contents are not returned.

Parameterspathrequiredbuild_reportprovenance_manifest

list_presets

List every pyobfus preset available, grouped by tier (community / framework-aware / Pro).

Takes no parameters.

explain_preset

Describe what a named preset changes: exclude names count, exclude patterns, preserve_param_names, docstring handling. For Pro presets, returns full pro_unlock metadata (trial command, checkout URL, price, money-back guarantee).

Parametersnamerequired

start_pro_trial

Return structured guidance for starting the 5-day pyobfus Pro trial. Does NOT invoke the side effect — the user runs `pyobfus-trial start` in their shell. Detects whether a trial is already active and surfaces the appropriate next step plus post-trial purchase URL.