🐍 mcp-python-repl

A production-grade MCP server providing a persistent Python REPL with multi-session support, sandboxing, and timeout protection.

Built for LLM agents that need to execute Python code across multiple turns with variables that persist between calls.

✨ Features

🚀 Quick Start

With Claude Desktop / Cursor (stdio)

Add to your MCP config:

{
  "mcpServers": {
    "python-repl": {
      "command": "uvx",
      "args": ["mcp-python-repl"]
    }
  }
}

With uv (local dev)

# Clone and run
git clone https://github.com/soufiane-aazizi/mcp-python-repl.git
cd mcp-python-repl
uv run mcp-python-repl

HTTP transport (remote / multi-client)

REPL_TRANSPORT=streamable-http REPL_PORT=8000 uv run mcp-python-repl

🛠️ Tools

Code Execution

Namespace Management

Session Management

Debugging

🔄 How Persistence Works

Call 1:  repl_run_code(code="data = [1,2,3]; total = sum(data); result = total")
         → returns: {"result": 6, "session_id": "a1b2c3d4e5f6", "new_variables": ["data", "total"]}

Call 2:  repl_run_code(code="doubled = [x*2 for x in data]; result = doubled", session_id="a1b2c3d4e5f6")
         → returns: {"result": [2,4,6], "new_variables": ["doubled"]}

Important: The result variable is for returning output to the caller. It does NOT persist. Use named variables instead.

⚙️ Configuration

All settings are configurable via environment variables:

Sandbox Mode

When REPL_SANDBOX=true, the following modules are blocked:

subprocess, shutil, ctypes, socket, http.server, xmlrpc, ftplib, smtplib, telnetlib, webbrowser

And the following builtins are removed: exec, eval, compile, __import__ (replaced with a restricted version).

🧪 Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest -v

# Lint
uv run ruff check src/ tests/

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run mcp-python-repl

📦 Project Structure

mcp-python-repl/
├── src/mcp_python_repl/
│   ├── __init__.py       # Package metadata
│   ├── config.py         # Env-based configuration
│   ├── session.py        # Multi-session manager with TTL
│   ├── executor.py       # Python code executor (timeout + sandbox)
│   └── server.py         # MCP server with all tools
├── tests/
│   └── test_core.py      # Unit + integration tests
├── pyproject.toml        # uv/hatch project config
├── LICENSE               # MIT
└── README.md

📄 License

MIT — See LICENSE.