mcp-python-repl
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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 ( |
Package install | Install pip packages on-the-fly (prefers |
File execution | Run |
Dual transport | stdio (local) and streamable-http (remote) |
Full introspection | List variables, get history, check server status |
Env-based config | All settings via |
Related MCP server: production-grade-mcp-agentic-system
π 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-replHTTP transport (remote / multi-client)
REPL_TRANSPORT=streamable-http REPL_PORT=8000 uv run mcp-python-replπ οΈ Tools
Code Execution
Tool | Description |
| Execute Python code with persistent namespace |
| Execute a |
| Install a pip package (uses |
Namespace Management
Tool | Description |
| List all variables in a session |
| Get the full value of a variable |
| Inject a variable from JSON |
| Delete a specific variable |
| Clear all variables in a session |
Session Management
Tool | Description |
| List all active sessions |
| Delete a session and its data |
Debugging
Tool | Description |
| Get execution history for a session |
| 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
resultvariable 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 |
|
| Max execution time in seconds |
|
| Maximum concurrent sessions |
|
| Session expiry in minutes |
|
| Max stdout/stderr capture (bytes) |
|
| Enable sandboxing ( |
|
| Transport: |
|
| HTTP host (when using HTTP transport) |
|
| HTTP port (when using HTTP transport) |
|
| 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.
Available Tools
12 toolsrepl_clear_namespaceADestructiveIdempotent
Clear ALL variables from a session. Cannot be undone.
Returns: Confirmation with list of cleared variables.
Inputs: params (required). Returns: result
repl_delete_sessionBDestructiveIdempotent
Delete a session and all its data.
Returns: Confirmation message.
Inputs: params (required). Returns: result
repl_delete_variableADestructiveIdempotent
Delete a specific variable from a session's namespace.
Returns: Confirmation with remaining variables.
Inputs: params (required). Returns: result
repl_get_historyARead-onlyIdempotent
Get the last N execution records for a session.
Useful for debugging what happened in previous calls.
Returns: JSON array of execution records.
Inputs: params (required). Returns: result
repl_get_variableARead-onlyIdempotent
Retrieve the full value of a variable from a session.
Returns: JSON with the variable name, type, and serialized value.
Inputs: params (required). Returns: result
repl_install_packageAIdempotent
Install a Python package using pip (or uv if available).
The package becomes importable in all sessions immediately.
Args:
params: Package specifier (e.g. pandas, requests>=2.31).
Returns: JSON with installation status and output.
Inputs: params (required). Returns: result
repl_list_namespaceBRead-onlyIdempotent
List all variables stored in a session's namespace.
Returns: JSON with variable names, types, and preview values.
Inputs: params (required). Returns: result
repl_list_sessionsARead-onlyIdempotent
List all active REPL sessions.
Returns: JSON array of sessions with IDs, timestamps, and variable counts.
Inputs: no named parameters. Returns: result
repl_run_codeA
Execute Python code with a PERSISTENT namespace.
Variables you assign are STORED and available in subsequent calls.
Access them DIRECTLY by name (e.g. my_data, df).
The result variable is ONLY for returning output to the caller.
It does NOT persist between calls β use named variables instead.
Correct workflow::
Call 1: data = load_csv("input.csv"); result = f"loaded {len(data)} rows"
Call 2: filtered = [r for r in data if r["active"]]; result = len(filtered)Returns: JSON with execution result, new/modified variables, and namespace summary.
Inputs: params (required). Returns: result
repl_run_fileA
Execute a Python file inside the persistent session.
Variables defined in the file become available for later use.
Args: params: File path, optional session ID, and optional CLI args.
Returns: JSON with execution result, file metadata, and namespace summary.
Inputs: params (required). Returns: result
repl_server_statusARead-onlyIdempotent
Get current server status and configuration.
Returns: JSON with Python version, session count, configuration, and limits.
Inputs: no named parameters. Returns: result
repl_set_variableAIdempotent
Set a variable in a session from a JSON string.
Useful for injecting data from external sources.
Returns: Confirmation with variable type and preview.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 12 tools
Each tool targets a distinct operation: running code vs. running files, managing variables (list/get/set/delete/clear), managing sessions (list/delete), plus package installation, history, and server status. There is no overlap between tools; even run_code vs. run_file is clearly separated by input type.
All tools follow a 'repl_' prefix and mostly use verb_noun naming (run_code, list_namespace, get_variable, delete_session). The only deviation is 'repl_server_status', which uses noun_noun instead of verb_noun, but this is a minor inconsistency in an otherwise uniform pattern.
With 12 tools, the server is well-scoped for a Python REPL session manager. Each tool addresses a distinct needβexecution, package management, namespace introspection, session lifecycle, history, and statusβwithout redundancy or bloat, fitting comfortably in the ideal 3-15 range.
The tool surface covers core REPL workflows: running code, running files, installing packages, managing namespace variables, listing/deleting sessions, retrieving history, and server status. Minor gaps exist, such as no explicit 'create session' tool (though sessions appear to be implicit) and no batch execution or session renaming, but these are not critical for typical usage.
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for agentverse documentation, generated by doc2mcp.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProduction-ready MCP server for secure Python code execution with artifact capture, virtual environment support, and LM Studio integration.11Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA production-grade MCP server designed for multi-tenant, authenticated, and observable AI agent systems, enabling secure tool execution across heterogeneous data sources.68MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for secure, session-based Python code execution in Docker containers, enabling LLM applications to run code, manage state, and access files.9MIT
- AlicenseNot gradedqualityDmaintenanceA secure, production-grade MCP server that provides filesystem operations, AST math evaluation, and system diagnostics for LLM agents.MIT