Content
# 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](https://www.docker.com/products/docker-desktop/)
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](https://claude.ai/download).
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`:
```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:
```json
{
"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:
```json
{
"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:
```dockerfile
# 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:
```bash
docker build -t custom-python-runner .
```
4. Run the container with your customized image:
```bash
docker run -v /path/to/your/project:/project -i custom-python-runner
```
## License
MIT
MCP Store
