What is Python Runner Mcp

python_runner_mcp is a Python code execution server built on the FastMCP framework, tailored for data science and machine learning workflows.

Use cases

Use cases include data analysis, machine learning model training, interactive development with Jupyter, and real-time data visualization.

How to use

To use python_runner_mcp, run the server using the command ‘uvx python-runner’ without any prior installation. Configure it in your Claude Desktop config file to integrate it seamlessly.

Key features

Key features include safe Python code execution in isolated namespaces, pre-installed data science libraries, real-time output capture, full MCP protocol support, and a user-friendly API interface.

Where to use

python_runner_mcp is ideal for data science, machine learning, and any application requiring safe and efficient execution of Python code.

Python Runner MCP Server

English | 中文

A Python code execution server based on the FastMCP framework, designed specifically for data science and machine learning workflows.

🚀 Features

• Safe Python Code Execution: Execute Python code in isolated namespaces
• Rich Data Science Libraries: Pre-installed with commonly used data science and machine learning packages
• Real-time Output Capture: Capture standard output, error output, and return values
• MCP Protocol Support: Fully compatible with Model Context Protocol
• Easy to Use: Provides a simple and clean API interface

⚡ Quick Start (Recommended)

Use uvx to run the server directly without installation: [TODO … ]

# Run directly (no pre-installation required)
uvx python-runner

Configure in Claude Desktop

Add the following configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "python-runner": {
      "command": "uvx",
      "args": [
        "python-runner"
      ]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Debug and Test

# Use MCP Inspector to debug the server
npx @modelcontextprotocol/inspector uvx python-runner

📦 Pre-installed Libraries

This project comes pre-installed with the following commonly used data science and machine learning libraries:

• Data Processing: numpy, pandas, scipy
• Machine Learning: scikit-learn
• Data Visualization: matplotlib, seaborn, plotly
• Scientific Computing: sympy
• Image Processing: pillow
• Network Analysis: networkx
• Interactive Development: jupyter
• HTTP Requests: requests

🛠️ Manual Installation (For Development)

Prerequisites

• Python 3.12 or higher
• uv package manager (recommended) or pip

Install with uv (Recommended)

# Clone the repository
git clone <repository-url>
cd python_runner

# Install dependencies
uv sync

Install with pip

# Clone the repository
git clone <repository-url>
cd python_runner

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

🚀 Usage

Using with Claude Desktop

After configuration, you can directly use Python code execution functionality in Claude Desktop:

Please help me execute this Python code:

import pandas as pd
import numpy as np

# Create sample data
data = pd.DataFrame({
    'sales': [100, 150, 200, 120, 180],
    'profit': [20, 30, 50, 25, 40]
})

print("Sales data statistics:")
print(data.describe())

Running as Standalone MCP Server

# Using uvx (recommended)
uvx python-runner

# Or run locally
python main.py

Direct API Call

from main import execute_python

# Execute simple Python code
result = execute_python("""
print("Hello, World!")
x = 1 + 2
print(f"Result: {x}")
""")

print(result)
# Output:
# {
#     'output': 'Hello, World!\nResult: 3\n',
#     'error': '',
#     'success': True
# }

Data Science Examples

# Data analysis example
code = """
import pandas as pd
import numpy as np

# Create sample data
data = pd.DataFrame({
    'x': np.random.randn(100),
    'y': np.random.randn(100)
})

print(f"Data shape: {data.shape}")
print(f"Statistical summary:\n{data.describe()}")
"""

result = execute_python(code)
print(result['output'])

# Machine learning example
code = """
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score

# Generate sample data
X, y = make_classification(n_samples=1000, n_features=20, random_state=42)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# Train model
clf = RandomForestClassifier(random_state=42)
clf.fit(X_train, y_train)

# Predict and evaluate
y_pred = clf.predict(X_test)
accuracy = accuracy_score(y_test, y_pred)
print(f"Model accuracy: {accuracy:.4f}")
"""

result = execute_python(code)
print(result['output'])

📋 API Reference

execute_python(code: str) -> dict

Execute Python code and return the result.

Parameters:

• code (str): Python code string to execute

Returns:

• dict: Dictionary containing the following keys:
  • output (str): Standard output content
  • error (str): Error message (if any)
  • success (bool): Whether execution was successful

🔒 Security

• Code executes in isolated namespaces
• Captures and redirects standard output and error output
• Provides detailed error tracking information

⚠️ Warning: This tool executes arbitrary Python code. Please ensure you use it in a trusted environment.

🤝 Contributing

Issues and Pull Requests are welcome!

1. Fork this repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastMCP - Excellent MCP framework
• All maintainers of the pre-installed open-source data science libraries

---

Made with ❤️ for the data science community