# Python Exec Sandbox [Health: Active]

**Category:** 👨‍💻 Code Execution  
**Repository:** https://github.com/lu-zhengda/mcp-python-exec-sandbox  
**GitHub Stars:** 1  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/python-exec-sandbox

## Description
Sandboxed Python execution for AI agents. PEP 723 inline deps, multi-version Python, zero pollution.

## Tools
Capabilities this server exposes over MCP:

- **execute_python** — Execute a Python script with automatic dependency management.

The script can include PEP 723 inline metadata (# /// script blocks)
for declaring dependencies. Additional dependencies can also be passed
via the dependencies parameter and will be merged.

Args:
    script: Python source code to execute. May include PEP 723 metadata.
    dependencies: Extra PEP 508 dependency specifiers to make available.
    timeout_seconds: Maximum execution time (1-300, default 30).

Returns:
    Formatted output with stdout, stderr, exit code, and duration.

Example - simple script:

    execute_python(script="print('hello')")

Example - with dependencies parameter:

    execute_python(
        script="import requests; print(requests.get('https://example.com').status_code)",
        dependencies=["requests>=2.32"]
    )

Example - with inline dependency metadata (preferred for multiple deps):

    execute_python(script='''
    # /// script
    # dependencies = ["pandas>=2.2", "numpy>=1.26"]
    # ///

    import pandas as pd
    import numpy as np
    print(pd.DataFrame({"a": np.arange(5)}).describe())
    ''')

Always pin dependency versions (e.g. "pandas>=2.2" instead of "pandas") for
reproducible results.

The inline metadata block (# /// script ... # ///) is the recommended way to
declare dependencies directly in the script (see PEP 723:
https://peps.python.org/pep-0723/). The dependencies parameter is a simpler
alternative when you just need to add a few packages. Both accept standard
pip-style version specifiers like "requests>=2.28" or "pandas" (see PEP 508:
https://peps.python.org/pep-0508/).
- **check_environment** — Check the execution environment and report status.

Returns information about Python version, uv version, platform,
sandbox configuration, and cache status.
- **validate_script** — Validate a Python script's PEP 723 metadata and dependencies without executing it.

Checks metadata syntax, dependency format, and requires-python compatibility.

Args:
    script: Python source code to validate. May include inline dependency
        metadata (# /// script blocks, see https://peps.python.org/pep-0723/).
    dependencies: Extra dependency specifiers to validate, using standard
        pip-style format like "requests>=2.28" (see https://peps.python.org/pep-0508/).

Returns:
    Validation result with metadata details or error information.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/python-exec-sandbox/readme_