github.com/yzfly/mcp-python-interpreter

MCP Python Interpreter

A Model Context Protocol (MCP) server that allows LLMs to interact with Python environments, read and write files, execute Python 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 files of any type (text, source code, binary)
  • Write text and binary files
• Python Prompts: Templates for common Python tasks like function creation and debugging

Installation

You can install the MCP Python Interpreter using pip:

pip install mcp-python-interpreter

Or with uv:

uv install mcp-python-interpreter

Usage with Claude Desktop

• Install Claude Desktop
• Open Claude Desktop, click on menu, then Settings
• Go to Developer tab and click "Edit Config"
• Add the following to your 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
        },
    }
  }
}

• Restart Claude Desktop
• You should now see the MCP tools icon in the chat interface

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

Prerequisites

• Make sure you have uv installed. If not, install it using:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• For Windows:

  powershell -ExecutionPolicy Bypass -Command "iwr -useb https://astral.sh/uv/install.ps1 | iex"
  

Available Tools

The Python Interpreter provides the following tools:

Environment and Package Management

• list_python_environments: List all available Python environments (system and conda)
• list_installed_packages: List packages installed in a specific environment
• install_package: Install a Python package in a specific environment

Code Execution

• run_python_code: Execute Python code in a specific environment
• run_python_file: Execute a Python file in a specific environment

File Operations

• read_file: Read contents of any file type, with size and safety limits
  • Supports text files with syntax highlighting
  • Displays hex representation for binary files
• write_file: Create or overwrite files with text or binary content
• write_python_file: Create or overwrite a Python file specifically
• list_directory: List Python files in a directory

Available Resources

• python://environments: List all available Python environments
• python://packages/{env_name}: List installed packages for a specific environment
• python://file/{file_path}: Get the content of a Python file
• python://directory/{directory_path}: List all Python files in a directory

Prompts

• python_function_template: Generate a template for a Python function
• refactor_python_code: Help refactor Python code
• debug_python_error: Help debug a Python error

Example Usage

Here are some examples of what you can ask Claude to do with this MCP server:

• "Show me all available Python environments on my system"
• "Run this Python code in my conda-base environment: print('Hello, world!')"
• "Create a new Python file called 'hello.py' with a function that says hello"
• "Read the contents of my 'data.json' file"
• "Write a new configuration file with these settings..."
• "List all packages installed in my system Python environment"
• "Install the requests package in my system Python environment"
• "Run data_analysis.py with these arguments: --input=data.csv --output=results.csv"

File Handling Capabilities

The MCP Python Interpreter now supports comprehensive file operations:

• Read text and binary files up to 1MB
• Write text and binary files
• Syntax highlighting for source code files
• Hex representation for binary files
• Strict file path security (only within the working directory)

Security Considerations

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

• Isolated working directory
• File size limits
• Prevented writes outside the working directory
• Explicit overwrite protection

Always be cautious about running code or file operations that you don't fully understand.

License

MIT