📌Overview

Purpose: The framework aims to provide an interactive Python REPL environment for executing and managing Python code seamlessly.

Overview: The python_local MCP Server serves as an interactive REPL (Read-Eval-Print Loop) platform, allowing users to execute Python code while retaining the state between sessions. This environment supports efficient management of execution history, enabling users to revisit prior commands and outputs.

Key Features:

REPL Session Management: Users can access session history through a custom repl:// URI scheme, allowing for tracking and reviewing previous code executions and their outputs.
Persistent Python Execution: The python_repl tool enables the execution of Python code in a continuous session, maintaining isolated states for each session and supporting both expressions and statements, while capturing stdout and stderr outputs.

python_local MCP Server

An MCP Server that provides an interactive Python REPL (Read-Eval-Print Loop) environment.

Components

Resources

The server provides access to REPL session history:

Custom repl:// URI scheme for accessing session history
Each session's history can be viewed as a text/plain resource
History shows input code and corresponding output for each execution

Tools

The server implements one tool:

python_repl: Executes Python code in a persistent session
- Takes code (Python code to execute) and session_id as required arguments
- Maintains separate state for each session
- Supports both expressions and statements
- Captures and returns stdout/stderr output

Configuration

Install

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration:

"mcpServers": {
  "python_local": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/python_local",
      "run",
      "python_local"
    ]
  }
}

Published Servers Configuration:

"mcpServers": {
  "python_local": {
    "command": "uvx",
    "args": [
      "python_local"
    ]
  }
}

Development

Building and Publishing

To prepare the package for distribution:

Sync dependencies and update lockfile:

uv sync

Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

Publish to PyPI:

uv publish

Set PyPI credentials via environment variables or command flags:

Token: --token or UV_PUBLISH_TOKEN
Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best experience, we strongly recommend using the MCP Inspector available at https://github.com/modelcontextprotocol/inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /path/to/python_local run python-local

Upon launching, the Inspector will display a URL to access in your browser to begin debugging.

python_mcp