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 tool install mcp-python-interpreter

Usage with Claude Desktop

1. Install Claude Desktop
2. Open Claude Desktop, click on menu, then Settings
3. Go to Developer tab and click "Edit Config"
4. 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"
        }
    }
  }
}

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

The --dir parameter sets the working directory (default: the directory where the server starts). File tools and run_python_code(save_as=...) restrict paths to this directory unless MCP_ALLOW_SYSTEM_ACCESS=1 is set. It is not a sandbox for executed Python code.

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 inline or in a subprocess. Optional save_as saves a .py file before execution; existing files require overwrite=true. A rejected save does not execute the code.
• 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
• File-tool path checks within the working directory by default, including save_as

Security Considerations

File tools and run_python_code(save_as=...) check resolved paths, including symlinks, against the working directory unless MCP_ALLOW_SYSTEM_ACCESS=1 is explicitly enabled. Existing files require an explicit overwrite flag; saved snippets use exclusive creation by default.

Inline and subprocess execution run arbitrary Python with the server user's permissions. They can access files or the network independently of these file-tool checks. A subprocess separates interpreter state; it is not an operating-system sandbox. Run only trusted code, or isolate the entire server with a container or a restricted user account. Inline execution has no enforced timeout. sys.exit() is reported as an execution error without stopping the MCP server.

MCP SDK compatibility

Version 1.2.5 supports MCP Python SDK 1.x (FastMCP) and 2.x (MCPServer). The standalone fastmcp package is not required. The MCP_TRANSPORT, MCP_HOST, MCP_PORT, MCP_JSON_RESPONSE, MCP_STATELESS_HTTP, and transport-security environment settings work with either SDK version.

License

MIT