Skip to main content
Glama
mcp-python-repl

mcp-python-repl

🐍 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: 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-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.

Available Tools

12 tools
repl_clear_namespaceA
DestructiveIdempotent

Clear ALL variables from a session. Cannot be undone.

Returns: Confirmation with list of cleared variables.

Inputs: params (required). Returns: result

repl_delete_sessionB
DestructiveIdempotent

Delete a session and all its data.

Returns: Confirmation message.

Inputs: params (required). Returns: result

repl_delete_variableA
DestructiveIdempotent

Delete a specific variable from a session's namespace.

Returns: Confirmation with remaining variables.

Inputs: params (required). Returns: result

repl_get_historyA
Read-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_variableA
Read-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_packageA
Idempotent

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_namespaceB
Read-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_sessionsA
Read-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_statusA
Read-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_variableA
Idempotent

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

    A4/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers