Python Exec Sandbox

mcp-python-exec-sandbox

[CI] [PyPI] [Python] [License]

Sandboxed Python execution for AI agents. Scripts run in ephemeral, isolated environments with inline dependencies (PEP 723) -- zero host pollution, zero leftover venvs, zero package conflicts.

Why?

Every coding agent can already run Python on your host. The problem is what happens next: packages accumulate, venvs sprawl, and a rogue pip install breaks your system. mcp-python-exec-sandbox eliminates this:

• Scripts execute in a sandbox (bubblewrap on Linux, Docker on macOS/other platforms)
• Dependencies are declared inline and resolved ephemerally via uv
• Nothing touches your host's Python, site-packages, or virtualenvs
• Each execution is isolated and disposable

Features

• Sandboxed execution -- platform-specific isolation prevents host filesystem access
• PEP 723 inline metadata -- declare dependencies directly in scripts with # /// script blocks
• Multi-version Python -- run scripts on Python 3.13, 3.14, or 3.15 (uv downloads the right version automatically)
• Ephemeral environments -- dependencies are resolved per-execution, never persisted
• Package caching -- uv's global cache makes repeat installs near-instant
• Timeout enforcement -- configurable per-execution timeouts
• Output truncation -- prevents runaway output from overwhelming the agent

Prerequisites

All setups require:

• Python 3.13+ -- to run the MCP server process
• uv -- manages script execution, dependency resolution, and Python version downloads. Also provides uvx for running the server without installing it globally.

Additional requirements depend on your chosen sandbox backend:

Host Python vs. execution Python: These are independent. Python 3.13+ is needed to run the server process itself. The --python-version flag controls which Python version your scripts execute on -- uv downloads the target version automatically. You do not need to install Python 3.14 or 3.15 on your host to run scripts on those versions.

Quick start

Claude Code (Linux -- native sandbox)

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox

Claude Code (macOS -- Docker sandbox, recommended)

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox

The Docker sandbox image is pulled automatically from GHCR on first use. No manual build required.

Claude Code (no sandbox)

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox --sandbox-backend none

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{  "mcpServers": {    "python-sandbox": {      "command": "uvx",      "args": ["mcp-python-exec-sandbox"]    }  }}

OpenAI Codex CLI

codex mcp add python-sandbox -- uvx mcp-python-exec-sandbox

Or add to .codex/config.toml:

[mcp_servers.python-sandbox]command = "uvx"args = ["mcp-python-exec-sandbox"]

Other MCP clients

Any client that supports the MCP stdio transport can use this server:

{  "mcpServers": {    "python-sandbox": {      "command": "uvx",      "args": ["mcp-python-exec-sandbox"]    }  }}

Multi-version Python

Use --python-version to target a specific Python version. uv downloads it automatically -- no manual install needed.

# Python 3.13 (default)uvx mcp-python-exec-sandbox --python-version 3.13
# Python 3.14uvx mcp-python-exec-sandbox --python-version 3.14
# Python 3.15uvx mcp-python-exec-sandbox --python-version 3.15

This works across all sandbox backends. The Docker sandbox uses uv inside the container to manage Python versions, so the same --python-version flag applies.

Tools

execute_python

Execute a Python script with automatic dependency management.

# Simple scriptexecute_python(script="print('hello world')")
# Script with dependenciesexecute_python(    script="import requests; print(requests.get('https://httpbin.org/get').status_code)",    dependencies=["requests"])
# Script with inline PEP 723 metadataexecute_python(script="""# /// script# dependencies = ["pandas", "matplotlib"]# ///
import pandas as pdprint(pd.DataFrame({'a': [1,2,3]}).describe())""")

check_environment

Returns information about the execution environment: Python version, uv version, platform, sandbox status, and configuration.

validate_script

Validates a script's PEP 723 metadata and dependencies without executing it.

Sandbox backends

The default backend is native (bubblewrap) on Linux and docker on macOS/other platforms. Specifying --sandbox-backend native on macOS automatically redirects to Docker. If the sandbox tool is unavailable, the server falls back to none with a warning.

Docker sandbox setup

The Docker sandbox image is published to GHCR and pulled automatically when the server starts. No manual setup is needed.

To build locally for development:

docker build -t ghcr.io/lu-zhengda/mcp-python-exec-sandbox profiles/

CLI options

mcp-python-exec-sandbox [OPTIONS]
Options:  --python-version TEXT     Python version for execution (default: 3.13)  --sandbox-backend TEXT    native | docker | none (default: native on Linux, docker on macOS)  --max-timeout INT         Maximum allowed timeout in seconds (default: 300)  --default-timeout INT     Default timeout in seconds (default: 30)  --max-output-bytes INT    Maximum output size in bytes (default: 102400)  --no-warm-cache           Skip cache warming on startup  --uv-path TEXT            Path to uv binary (default: uv)

Development

Setup

git clone https://github.com/lu-zhengda/mcp-python-exec-sandbox.gitcd mcp-python-exec-sandboxuv sync --dev

Project structure

src/mcp_python_exec_sandbox/   # Package source  server.py               # FastMCP server + tool definitions  executor.py             # uv subprocess orchestration  script.py               # PEP 723 metadata parsing/merging  sandbox.py              # Sandbox ABC + factory  sandbox_linux.py        # bubblewrap sandbox (Linux)  sandbox_docker.py       # Docker sandbox (macOS/any)  config.py, cache.py, output.py, errors.pytests/                    # Unit + integration tests (mocked or local uv)e2e_tests/                # End-to-end tests (require uv + network)profiles/                 # Dockerfile, warmup packages.devcontainer/            # Devcontainer for Linux sandbox testing from macOS

Running tests

Unit and integration tests -- fast, run everywhere:

uv run pytest tests/ -v

E2E tests -- require uv and network access. These exercise real script execution, package installation, MCP protocol flow, and sandbox enforcement:

uv run pytest e2e_tests/ -v

Docker sandbox tests

The Docker E2E tests (e2e_tests/test_docker_sandbox.py) verify execution, dependency installation, read-only filesystem enforcement, host isolation, and timeout handling through the Docker backend.

Prerequisites:

1. Docker must be installed and running
2. Build the sandbox image:

docker build -t ghcr.io/lu-zhengda/mcp-python-exec-sandbox profiles/

Then run:

uv run pytest e2e_tests/test_docker_sandbox.py -v

These tests are automatically skipped if Docker is unavailable or the image hasn't been built.

Linux sandbox tests (devcontainer)

The Linux sandbox tests (e2e_tests/test_sandbox_enforcement.py::test_linux_sandbox_blocks_etc_shadow) use bubblewrap (bwrap) for namespace isolation. They are skipped on macOS because bwrap is Linux-only.

To run them from macOS, use the included devcontainer which provides Ubuntu 24.04 with bwrap pre-installed:

VS Code:

1. Install the Dev Containers extension
2. Open the project and select Reopen in Container
3. In the integrated terminal:

uv run pytest e2e_tests/test_sandbox_enforcement.py -v

CLI:

# Install the devcontainer CLI (once)npm install -g @devcontainers/cli
# Build and start the containerdevcontainer up --workspace-folder .
# Run the Linux sandbox tests inside the containerdevcontainer exec --workspace-folder . uv run pytest e2e_tests/test_sandbox_enforcement.py -v

Test matrix

Contributing

• One logical change per commit. Descriptive commit message (imperative mood).
• Run uv run pytest tests/ -v before committing -- all tests must pass.
• Add tests for new functionality: unit tests in tests/, E2E in e2e_tests/ if it needs real execution.
• Keep dependencies minimal. Do not add runtime deps without strong justification.
• Tool docstrings in server.py are user-facing MCP tool descriptions. Write them for an LLM audience.
• Sandbox backends must degrade gracefully: if the required tool (bwrap, docker) is missing, fall back to NoopSandbox with a warning.

License

MIT