mcp-pyrepl

Nearly everything is vibe-coded using https://eca.dev. This repo will not be properly maintained by me. Currently, it is just a playground!

An MCP (Model Context Protocol) server that provides a Python REPL with execution state.

Overview

This MCP server allows you to execute Python code while maintaining state between executions. Variables and globals persist within the server process but are not persisted to disk.

Features

• Execute Python code with persistent global state
• Three available tools: execute, get_globals, and reset_globals
• State persists within the server process (resets on server restart)

Installation

Prerequisites

• Python 3.12+
• uv package manager

Install Dependencies

make install

Or using uv directly:

uv sync

Install in Editable Mode

make install-editable

Or:

uv pip install -e .

Running the Server

Development Mode

make run

Or:

uv run python src/main.py

The server will start and can be connected to via MCP clients.

Usage with MCP Clients

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "pyrepl": {
      "command": "uv",
      "args": ["run", "python", "src/main.py"],
      "env": {},
      "cwd": "/path/to/mcp-pyrepl"
    }
  }
}

Other MCP Clients

The server exposes three tools:

1. execute

Execute Python code and get the result.

# Example: Assign a variable
execute(code="x = 5")
# Returns: {"success": true, "result": "5", "globals_keys": ["x"]}

# Example: Use a previously assigned variable
execute(code="x * 2")
# Returns: {"success": true, "result": "10", "globals_keys": ["x"]}

# Example: Import and use a module
execute(code="import math; math.sqrt(16)")
# Returns: {"success": true, "result": "4.0", "globals_keys": ["x", "math"]}

2. get_globals

View all current global variables.

get_globals()
# Returns: {"x": "5", "math": "<module 'math' from ...>"}

3. reset_globals

Clear all global variables and start fresh.

reset_globals()
# Returns: {"status": "globals reset"}

Development Commands

Command	Description
make install	Install dependencies with uv sync
make install-editable	Install package in editable mode
make run	Run the MCP server
make test	Run tests
make lint	Run linter
make format	Format code
make all	Run install, lint, format, and test

Notes

• Variables persist within the server process only
• Server restart will reset all globals