Content
# 🐍 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
| Feature | Description |
|---|---|
| **Multi-session** | Isolated sessions with unique IDs — run parallel workflows |
| **Persistent namespace** | Variables survive across calls within a session |
| **Timeout protection** | Configurable execution timeout (SIGALRM on Unix) |
| **Sandboxing** | Optional mode blocks dangerous modules (`subprocess`, `socket`, etc.) |
| **Package install** | Install pip packages on-the-fly (prefers `uv` for speed) |
| **File execution** | Run `.py` files inside the persistent session |
| **Dual transport** | stdio (local) and streamable-http (remote) |
| **Full introspection** | List variables, get history, check server status |
| **Env-based config** | All settings via `REPL_*` environment variables |
## 🚀 Quick Start
### With Claude Desktop / Cursor (stdio)
Add to your MCP config:
```json
{
"mcpServers": {
"python-repl": {
"command": "uvx",
"args": ["mcp-python-repl"]
}
}
}
```
### With uv (local dev)
```bash
# 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)
```bash
REPL_TRANSPORT=streamable-http REPL_PORT=8000 uv run mcp-python-repl
```
## 🛠️ Tools
### Code Execution
| Tool | Description |
|---|---|
| `repl_run_code` | Execute Python code with persistent namespace |
| `repl_run_file` | Execute a `.py` file in the session |
| `repl_install_package` | Install a pip package (uses `uv` if available) |
### Namespace Management
| Tool | Description |
|---|---|
| `repl_list_namespace` | List all variables in a session |
| `repl_get_variable` | Get the full value of a variable |
| `repl_set_variable` | Inject a variable from JSON |
| `repl_delete_variable` | Delete a specific variable |
| `repl_clear_namespace` | Clear all variables in a session |
### Session Management
| Tool | Description |
|---|---|
| `repl_list_sessions` | List all active sessions |
| `repl_delete_session` | Delete a session and its data |
### Debugging
| Tool | Description |
|---|---|
| `repl_get_history` | Get execution history for a session |
| `repl_server_status` | Server config, Python version, session count |
## 🔄 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:
| Variable | Default | Description |
|---|---|---|
| `REPL_TIMEOUT` | `30` | Max execution time in seconds |
| `REPL_MAX_SESSIONS` | `50` | Maximum concurrent sessions |
| `REPL_SESSION_TTL` | `120` | Session expiry in minutes |
| `REPL_MAX_OUTPUT` | `1048576` | Max stdout/stderr capture (bytes) |
| `REPL_SANDBOX` | `false` | Enable sandboxing (`true`/`false`) |
| `REPL_TRANSPORT` | `stdio` | Transport: `stdio` or `streamable-http` |
| `REPL_HOST` | `127.0.0.1` | HTTP host (when using HTTP transport) |
| `REPL_PORT` | `8000` | HTTP port (when using HTTP transport) |
| `REPL_WORKDIR` | `cwd` | Working directory for executions |
### 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
```bash
# 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](LICENSE).
