Python REPL MCP Server

This is a fork of hdresearch/mcp-python, a Python REPL server for MCP protocol. But seems almost nothing is left from the original code.

This MCP server provides a Python REPL (Read-Eval-Print Loop) as a tool. It allows execution of Python code through the MCP protocol with a persistent session.

Setup

No setup needed! The project uses uv for dependency management. All dependencies are automatically managed through the pyproject.toml file.

Environment Variables

The server supports .env file for environment variables management. Create a .env file in the root directory to store your environment variables. These variables will be automatically loaded and accessible in your Python REPL session using:

import os

# Access environment variables
my_var = os.environ.get('MY_VARIABLE')
# or
my_var = os.getenv('MY_VARIABLE')

Running the Server

Simply run:

uv run mcp_python

Usage with Claude Desktop

Add this configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "python-repl": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/python-repl-server",
        "run",
        "mcp_python"
      ]
    }
  }
}

Available Tools

The server provides the following tools:

1. execute_python: Execute Python code with persistent variables

   • code: The Python code to execute

   • reset: Optional boolean to reset the session

2. list_variables: Show all variables in the current session

3. install_package: Install a package from PyPI using uv

   • package: Name of the package to install

4. initialize_project: Create a new project directory with timestamp prefix

   • project_name: Name for the project directory

5. create_file: Create a new file with specified content

   • filename: Path to the file (supports nested directories)

   • content: Content to write to the file

6. load_file: Load and execute a Python script in the current session

   • filename: Path to the Python script to load

Features

• Persistent Python REPL session

• Automatic environment variable loading from .env files

• Package management using uv

• Project initialization with timestamped directories

• File creation and management

• Script loading and execution

• Comprehensive logging system

• Support for nested project structures

Examples

Initialize a new project:

# Create a new project directory
initialize_project("my_project")

Create and execute a script:

# Create a new Python file
create_file("script.py", """
def greet(name):
    return f"Hello, {name}!"
""")

# Load and execute the script
load_file("script.py")

# Use the loaded function
print(greet("World"))

Install and use a package:

# Install pandas
install_package("pandas")

# Use the installed package
import pandas as pd
df = pd.DataFrame({'A': [1, 2, 3]})
print(df)

List all variables:

# Show all variables in the current session
list_variables()

Reset the session:

# Use execute_python with reset=true to clear all variables
execute_python("", reset=True)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Here are some ways you can contribute:

• Report bugs

• Suggest new features

• Improve documentation

• Add test cases

• Submit code improvements

Before submitting a PR, please ensure:

1. Your code follows the existing style

2. You've updated documentation as needed

3. All tests pass

4. You've added tests for new features

For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.