python-runner

Python MCP Server

An MCP (Model Context Protocol) server that exposes a run_script tool for executing Python code via subprocess.

Installation

uv sync

Usage

Run the server

uv run python server.py

Claude Desktop / Claude Code

claude mcp add --transport stdio --scope user python-runner -- uvx --from git+https://github.com/Drahoxx/python-mcp python-mcp

Or for a local installation:

claude mcp add --transport stdio --scope user python-runner -- uv run --directory /path/to/python-mcp python-mcp

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "python-runner": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Drahoxx/python-mcp", "python-mcp"]
    }
  }
}

Or for a local installation:

{
  "mcpServers": {
    "python-runner": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/python-mcp", "python-mcp"]
    }
  }
}

Generic MCP Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "python-runner": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/python-mcp", "python", "server.py"]
    }
  }
}

Tool: run_script

Execute Python code and return the result.

Parameters

| Name | Type | Default | Description | |------|------|---------|-------------| | code | str | required | Python code to execute | | timeout | int | 30 | Execution timeout in seconds |

Response

Returns a JSON string with:

| Field | Type | Description | |-------|------|-------------| | success | bool | Whether execution succeeded (exit code 0) | | stdout | str | Captured standard output | | stderr | str | Captured standard error | | error | str \| null | Error message/traceback if failed | | return_code | int | Process exit code (-1 for timeout) |

Examples

Successful execution: ```python run_script('print("hello")')

{"success": true, "stdout": "hello\n", "stderr": "", "error": null, "return_code": 0}

**Syntax error:**

run_script('print(')

{"success": false, "stdout": "", "stderr": "...", "error": "SyntaxError...", "return_code": 1}

**Runtime error:**

run_script('1/0')

{"success": false, "stdout": "", "stderr": "...", "error": "ZeroDivisionError...", "return_code": 1}

**Timeout:**

run_script('import time; time.sleep(60)', timeout=2)

{"success": false, "stdout": "", "stderr": "", "error": "Execution timed out after 2 seconds", "return_code": -1}

## Development

### Run tests

uv run pytest ```

Run tests with coverage

uv run pytest --cov=server