What is Mcp Python

This project is a Python REPL server that implements the MCP protocol, allowing users to execute Python code in a persistent session. Forked from the original mcp-python project, it offers a series of tools and features designed to enhance the coding experience in a REPL environment.

Use cases

The server can be used for various tasks such as executing Python code dynamically, managing project directories and files, installing packages from PyPI, and maintaining a persistent workspace that retains variables and session state across multiple interactions.

How to use

To run the server, execute the command ‘uv run mcp_python’ in your terminal. For integration with Claude Desktop, add the specified configuration in its config file, replacing the path with the path to the Python REPL server. Once set up, you can utilize available tools to create files, execute code, and manage variables.

Key features

The server includes a persistent REPL session, automatic loading of environment variables from a .env file, package management, project initialization, file creation, and script execution. It also features a robust logging system and supports nested project structure management.

Where to use

This MCP server can be utilized in development environments where quick code execution and testing are required, especially for projects that need dynamic code evaluation and management. It is ideal for developers using tools like Claude Desktop who seek an interactive Python coding experience.

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.