Python Runner

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:

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