What is Mcp Python Runner

mcp-python-runner is a Model Context Protocol (MCP) server designed to enable Large Language Models (LLMs) to execute Python code, create plots, visualizations, and data files.

Use cases

Use cases include running Python scripts for data processing, generating visualizations for reports, creating interactive data applications, and executing complex algorithms in a secure environment.

How to use

To use mcp-python-runner, install Docker and run the server using the provided Docker command. Configure your MCP client (like Claude Desktop) to connect to the server by adding the necessary configuration in the settings.

Key features

Key features include code execution, package management for installing additional Python packages, file operations for generating and reading various file types, and Docker support for running in an isolated container.

Where to use

mcp-python-runner can be used in fields such as data analysis, machine learning, scientific computing, and any application requiring dynamic code execution and data visualization.

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)

1. 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:

1. 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

2. Replace the packages with any libraries you commonly use (e.g., pytorch, seaborn, plotly, etc.)

3. Rebuild the Docker image:

docker build -t custom-python-runner .

4. Run the container with your customized image:

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

License

MIT