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

MCP Python Interpreter

Integrations