MCP Python Exec Sandbox

Provides sandboxed, inline-dependent Python execution for AI agents with ephemeral environments and per-run isolation.

python

0

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can run Python scripts for AI agents in complete isolation, with inline dependency declarations and ephemeral environments. This MCP server executes code in sandboxed environments so your host remains clean, with no lingering virtual environments or package conflicts while still allowing multi-version Python execution and automatic dependency resolution.

How to use

You connect an MCP client to the server using an MCP transport (stdio) and issue tool calls to execute Python code in a sandbox. The server mirrors common Python scripting workflows: provide the script, optionally declare dependencies inline or merge additional dependencies, and set a timeout to ensure executions stay within limits. Each run is isolated, uses a sandbox backend, and never pollutes your host Python installation.

How to install

Prerequisites: ensure you have Python 3.13+ on the host to run the MCP server process. You will also need uv to manage script execution and Python version downloads.

Backends and behavior

The server supports multiple sandbox backends and gracefully degrades if a tool is unavailable. By default, Linux uses a native sandbox (bubblewrap), while macOS and other platforms use Docker by default. If the required sandbox tool is missing, the server falls back to no sandbox with a warning. Each execution remains isolated and disposable, with dependencies resolved per-run and not persisted.

CLI options

You can configure the server using CLI options. Key options include selecting the Python version for execution, choosing the sandbox backend, and setting timeouts and output limits. The final runtime controls are applied per execution to prevent runaway processes.

Multi-version Python

Use the Python version flag to target a specific Python release. The server downloads the requested version automatically, so you do not need to install multiple interpreters on the host. This works across all sandbox backends.

Tools

execute_python — Execute a Python script with automatic dependency management. You provide the script, optional external dependencies, and a timeout. The server resolves and installs dependencies for that run.

check_environment — Return details about the execution environment, including Python version, uv version, platform, sandbox status, and configuration.

validate_script — Validate a script’s inline metadata and dependencies without executing it, ensuring the syntax and dependency declarations are correct.

Development and testing

Development involves unit and integration tests, plus end-to-end tests that exercise real script execution, package installation, MCP protocol flow, and sandbox enforcement. Docker and Linux bubblewrap backends have dedicated end-to-end tests.

Available tools

execute_python

Execute a Python script with automatic dependency management. Provide the script, optional extra dependencies, and a timeout. The server resolves and runs the code in an isolated sandbox.

check_environment

Return information about the current execution environment, including Python version, uv version, platform, and sandbox configuration.

validate_script

Validate a script’s PEP 723 metadata and dependencies without performing execution to ensure correctness before running.