MCP Python REPL Server

You run an MCP Python REPL Server to give Claude Code interactive, project-aware Python execution inside your development work. It activates your virtual environments, manages dependencies, loads project context, and lets you introspect code while keeping each session isolated to its own project workspace.

How to use

When you connect Claude Code to this server, you can create persistent REPL sessions that run inside your project’s environment. You can execute Python code in real time, inspect objects, inspect modules, and load your project modules so imports behave as they do when you run your app. You gain automatic virtual environment awareness, environment variable handling, and integration with common development tools. You can install dependencies, format and lint code, run tests, and interact with your codebase directly from the REPL.”}oot=

How to install

Prerequisites you need before installing the MCP server:

• Python 3.11 or newer is required.

• The UV package manager is used to manage servers, virtual environments, and project dependencies.

Follow one of the installation flows below to set up the MCP server locally.

Install flow A (development)

# Step 1: Clone and set up the project
git clone <repository-url>
cd mcp-py3repl
uv sync

# Step 2: Install the server locally for development
uv pip install -e .

# Optional: install from repository
# pip install git+<repository-url>

Install flow B (direct execution via module)

# Step 1: Install the server as a package for local use
uv pip install -e .

# Step 2: Run the server module directly
python -m mcp_py3repl.server

Install flow C (direct Python path to server file)

# Step 1: Ensure a virtual environment is available
# Step 2: Run the server directly from the source path
/path/to/mcp-py3repl/.venv/bin/python /path/to/mcp-py3repl/src/mcp_py3repl/server.py

Configuring Claude Code to use the server

Add MCP server configuration to Claude Code to enable communication with the Python REPL server. You can choose from multiple start methods depending on whether you run via uv, use a global Python install, or run a direct script.

Available tools

python_execute

Execute Python code in the active REPL session and return the execution result, standard output, and any errors.

python_inspect

Inspect Python objects, variables, or modules to retrieve type information, docstrings, and attributes.

session_create

Create a new REPL session with an optional name and working directory.

session_list

List all active REPL sessions with their status and configuration.

session_switch

Switch to a different REPL session by session identifier.

package_install

Install Python packages using uv, updating the project configuration as needed.

package_remove

Remove Python packages from the current environment and update dependencies accordingly.

package_list

List installed packages in the active environment with versions.

file_read_project

Read a file from the project directory within the active Python session, with encoding detection.

file_write_project

Write content to a file in the project directory with encoding detection and safety checks.

load_env_file

Load environment variables from a .env file into the current session.

set_env_var

Set a specific environment variable for the current session.

list_env_vars

List environment variables currently loaded in the session.

create_env_template

Generate a .env.example template from a pydantic Settings class.

format_file

Format a Python file using Black or Ruff.

lint_file

Lint a Python file using Ruff and optionally apply fixes.

run_tests

Run tests using pytest with optional path, pattern, and verbosity.

inspect_model

Inspect a Pydantic/SQLModel model to show fields, types, validators, and examples.

validate_data

Validate data against a specified model to surface validation errors.

generate_sample_data

Generate realistic sample data for a given model.

model_to_json_schema

Export a model’s OpenAPI/JSON schema.

create_test_tables

Create test SQLite tables from SQLModel models.

seed_test_data

Populate the test database with seed data for testing.

inspect_table

Inspect a database table’s schema and sample data.

setup_query_builder

Interactively build SQL queries with awareness of SQLModel models.

migration_status

Show current Alembic migration state.

create_migration

Create a new Alembic migration from changes.

auto_generate_migration

Auto-generate Alembic migrations from SQLModel changes.

run_migrations

Apply migrations to the target database.

reset_test_db

Reset the test database to a clean state by dropping and recreating tables.

migration_history

Display a timeline of migrations and changes.