How do I use mcp-python-repl?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-python-repl Calculate 10 factorial using a loop" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

🐍 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

Related MCP server: Sandbox MCP

🚀 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

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

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

This server cannot be installed

A

license - permissive license

-

quality - not tested

-

maintenance - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

mcp-python-repl