Python Exec Sandbox

What Python Exec Sandbox MCP server does

Python Exec Sandbox MCP server exposes Python execution through MCP for clients that support the stdio transport. Each script runs in a temporary environment, so installed packages and virtual environments are not left on the host. The server is intended for agent-driven scripts that may need third-party packages, a specific Python version, or controlled execution limits.

Dependency declarations can be included in the script using PEP 723 metadata, or supplied separately as PEP 508 dependency specifiers. The selected dependencies are resolved for the individual execution. uv maintains a global package cache, which can speed up later runs without making an execution environment persistent.

How it works

The server process requires Python 3.13 or newer and uses uv to manage script execution, dependency resolution, and Python downloads. The Python version used by the server and the Python version used for scripts are independent. By default, scripts target Python 3.13, but the command line can select versions such as 3.14 or 3.15.

Sandbox selection depends on the platform. Linux defaults to a native bubblewrap backend with namespace isolation and network access. macOS and other platforms default to Docker. The Docker image is pulled from GHCR when needed. A none backend is available, but it provides no sandboxing. If the configured sandbox tool is unavailable, the server falls back to none with a warning.

Setup and configuration

Install Python 3.13 or newer and uv. Linux users also need bubblewrap for the native backend. Docker is required for the Docker backend. The server can be started without a global package installation using uvx mcp-python-exec-sandbox.

Common options include:

• --python-version selects the execution Python version.
• --sandbox-backend selects native, docker, or none.
• --default-timeout sets the normal execution limit, defaulting to 30 seconds.
• --max-timeout caps permitted timeouts at 300 seconds by default.
• --max-output-bytes limits returned output, defaulting to 102400 bytes.
• --no-warm-cache disables startup cache warming.
• --uv-path specifies the uv executable location.

Cursor, Claude Code, and OpenAI Codex CLI examples are provided in the project documentation. Other MCP clients can use the same stdio configuration.

Tools and capabilities

Python Exec Sandbox MCP server provides three documented tools:

• execute_python runs required script source code, optionally merging a dependencies list. Its timeout_seconds parameter defaults to 30 seconds and accepts values from 1 to 300, subject to the server maximum.
• check_environment reports the execution Python version, uv version, platform, sandbox status, and configuration.
• validate_script checks PEP 723 metadata and dependency declarations without running the script.

Output truncation helps prevent an execution from returning more data than the configured byte limit. Dependency metadata may declare packages such as pandas or matplotlib directly in the source, while the separate dependency parameter supports additional specifications.

Limitations and notes

Sandbox behavior depends on the selected backend and its prerequisites. The none backend does not isolate execution and is not recommended when host protection is required. Native sandboxing is documented for Linux; requesting the native backend on macOS redirects to Docker.

Scripts can use network access with the native backend, while Docker provides container isolation and resource limits. Execution time is bounded by the request timeout and server maximum, and output may be truncated. Python versions beyond the server's own runtime are downloaded by uv rather than requiring those versions to be installed on the host.