MCP Python Interpreter

🚀 MCP Python Interpreter

An MCP (Model Context Protocol) server that enables LLMs to interact with Python environments, read and write files, execute Python code, and manage development workflows.

🚀 Quick Start

The MCP Python Interpreter is a powerful tool that allows LLMs to interact with Python environments, perform file operations, execute code, and manage development workflows.

✨ Features

• Environment Management: List and use different Python environments (system and conda).
• Code Execution: Run Python code or scripts in any available environment.
• Package Management: List installed packages and install new ones.
• File Operations:
  • Read any type of file (text, source code, binary).
  • Write text and binary files.
• Python Prompt Templates: Templates for common Python tasks, such as function creation and debugging.

📦 Installation

Install the MCP Python Interpreter using pip:

pip install mcp-python-interpreter

Or use uv:

uv install mcp-python-interpreter

💻 Usage Examples

Using with Claude Desktop

1. Install Claude Desktop.
2. Open Claude Desktop, click on the menu, and then select Settings.
3. Go to the Developer tab and click "Edit Configuration".
4. Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-python-interpreter": {
        "command": "uvx",
        "args": [
            "mcp-python-interpreter",
            "--dir",
            "/path/to/your/work/dir",
            "--python-path",
            "/path/to/your/python"
        ],
        "env": {
            "MCP_ALLOW_SYSTEM_ACCESS": 0
        }
    }
  }
}

For Windows:

{
  "mcpServers": {
    "python-interpreter": {
      "command": "uvx",
      "args": [
        "mcp-python-interpreter",
        "--dir",
        "C:\\path\\to\\your\\working\\directory",
        "--python-path",
        "/path/to/your/python"
      ],
        "env": {
            "MCP_ALLOW_SYSTEM_ACCESS": 0
        }
    }
  }
}

5. Restart Claude Desktop.
6. You should now see the MCP tool icon in the chat interface.

The --dir parameter is required and specifies the location where all files are saved and executed. This helps maintain security by isolating the MCP server to a specific directory.

Prerequisites

• Ensure that pip and uv are installed.
• Confirm that a Python interpreter is installed.

Basic Usage

# Example 1: Simple calculation
result = 2 + 3
print(result)  # Output: 5

# Example 2: File operation
with open("test.txt", "w") as f:
    f.write("Hello, World!")

📚 Documentation

Available Tools

• Environment Management: Supports multiple Python versions and automatically detects conda environments.
• Code Execution: Secure code sandbox with restricted file access.
• Package Management: Install and uninstall packages via pip and conda.
• File Operations: Strict control over file paths to prevent malicious writes.

Resources

• API Documentation: Details the functionality and usage of each interface.
• Sample Code: Provides usage examples for common scenarios.
• Troubleshooting: Common issues and solutions.

File Handling Capabilities

• File Reading: Supports text and binary files, with a maximum limit of 1MB.
• File Writing: Strictly controlled within the working directory.
• Syntax Highlighting: Highlighting for source code files.
• Hexadecimal Representation: Hexadecimal escape for binary files.

Security Considerations

This MCP server has access to your Python environment and file system. Key security features include:

• Isolated working directory.
• File size limits.
• Prevention of writing outside the working directory.
• Explicit overwrite protection.

Always exercise caution when running code or performing file operations that you do not fully understand.

📄 License

MIT