READMEmain

MCP Python Runner

A Model Context Protocol (MCP) server that allows LLMs to execute Python code, generate plots, visualizations and data files.

Features

Code Execution: Run Python code
Package Management: Install additional Python packages as needed
File Operations:
- Generate and read files of any type (text, source code, binary)
- Generate and display plots and visualizations
Docker Support: Run in an isolated container with optional pre-installed packages

Installation

Using Docker (Recommended)

Install Docker

That's it! The Docker image will be automatically pulled from DockerHub when you first run the server.

The server can then be used by an mcp client, like Claude Desktop.

To add the configuration to Claude Desktop, click on menu, then Settings. From Developer use Edit Config. Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "python-runner": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/your/work/dir:/project",
        "-e",
        "HOST_PROJECT_PATH=/path/to/your/work/dir",
        "cmbant/python-runner"
      ],
      "env": {
        "MCP_ALLOW_SYSTEM_ACCESS": 0
      }
    }
  }
}

For Windows:

{
  "mcpServers": {
    "python-runner": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "C:\\path\\to\\your\\work\\dir:/project",
        "-e",
        "HOST_PROJECT_PATH=C:\\path\\to\\your\\work\\dir",
        "cmbant/python-runner"
      ],
      "env": {
        "MCP_ALLOW_SYSTEM_ACCESS": 0
      }
    }
  }
}

Restart Claude Desktop

The -v parameter maps your local directory to the /project directory in the container, where all files will be saved and executed. This helps maintain security by isolating the MCP server. Any images or data files will remain available in your local directory after the container exits.

Using Local Installation (Not Recommended)

Note: The local installation method seems to hang (why?). So Docker installation is strongly recommended.

If you still want to try the local installation:

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

Prerequisites

For Docker setup: Docker Desktop installed and running
For local setup: Python 3.12+ and the mcp-python-runner package installed (or use uvx)

Available Tools

The Python Runner provides the following tools:

Code Execution

execute_python_code: Execute Python code with optional package requirements
- Automatically installs required packages
- Returns both text output and generated images
- Example: execute_python_code(code="import matplotlib.pyplot as plt; plt.plot([1,2,3]); plt.savefig('plot.png')", requirements="matplotlib")

File Operations

read_file: Read contents of any file type, with size and safety limits
- Supports reading various file formats including text and source code
- Displays hex representation for binary files
read_image_file: Read and display image files generated by Python code

Working Directory Management

The MCP Python Runner manages the working directory efficiently:

Maintains only a cache directory in the working directory
No .toml files or virtual environments are created in the working directory
Package installations are handled through the UV package manager

Customizing Pre-installed Packages

The Docker image comes with matplotlib and scipy pre-installed, but you can modify the Dockerfile to pre-install different common packages:

Edit the Dockerfile and add your desired packages to the build stage:

# Add this after the application installation
RUN uv pip install --python ${APP_VENV_DIR}/bin/python numpy pandas scikit-learn tensorflow

Replace the packages with any libraries you commonly use (e.g., pytorch, seaborn, plotly, etc.)
Rebuild the Docker image:

docker build -t custom-python-runner .

Run the container with your customized image:

docker run -v /path/to/your/project:/project -i custom-python-runner

License

MIT

mcp-python-runner