Pyrunner MCP

🚀 PyRunner MCP

A Persistent Kernel for Python Scripts, optimized for Python script development. It retains variables across executions and offers a Jupyter-like experience.

🚀 Quick Start

Prerequisites

• Python 3.8+
• Gemini CLI (Installation Guide)

Installation

# 1. Clone the project
git clone https://github.com/YOUR_USERNAME/PyRunner_MCP.git
cd PyRunner_MCP

# 2. Install dependencies
pip install fastmcp psutil

Configure the MCP Server

Edit ~/.gemini/settings.json:

{
    "mcpServers": {
        "PyRunner_MCP": {
            "command": "python",
            "args": ["C:/path/to/PyRunner_MCP/PyRunner_MCP.py"],
            "env": {
                "MCP_BASE_DIR": "C:/path/to/PyRunner_MCP"
            }
        }
    }
}

Start

cd /path/to/PyRunner_MCP
gemini chat

If you see this, it means you've succeeded:

✓ Connected to MCP server: PyRunner_MCP (16 tools)

Configure GEMINI.md (AI Behavior Guide)

Place GEMINI.md in the project root directory. It tells the AI:

• How to use PyRunner's tools
• Your development habits and technical preferences
• The priority of task execution

# Main content of GEMINI.md

## Core Functions
- Use the Persistent Kernel by default (use_kernel=True)
- Call reset_kernel() when the user says "reset"

## Checklist at the start of the conversation
1. kernel_status() - Check the kernel status
2. recall() - Load long-term memory
3. list_files() - Understand existing assets

## Technical Preferences
- Use requests + BeautifulSoup for web crawling
- Use webbrowser.open() to open web pages

Explanation of kernel_server.py

This is the Persistent Kernel process that runs in the background and does not need to be started manually:

┌──────────────────┐      socket       ┌──────────────────┐
│  PyRunner_MCP.py │  ◄───────────►    │ kernel_server.py │
│   (MCP Server)   │   127.0.0.1:9999  │  (Python Kernel) │
└──────────────────┘                   └──────────────────┘
                                              │
                                              ▼
                                    global_namespace = {}
                                    (All variables are stored here)

Auto-Safe Mode - "The Vaccine":

• Unified Process Core: All subprocesses (Python/Pip/Shell) are driven by a unified core, forcing output redirection and environment purification.
• Deadlock Immunity: Completely solve the deadlock problem caused by full Pipe Buffer or DLL locking on Windows.
• Auto Monkey Patch: Automatically intercept the multi-threaded behavior of libraries such as yfinance to ensure kernel stability.

💡 Usage Tip

It is now recommended to use use_kernel=True (Direct Kernel Mode) for all tasks. The system has built-in protection, so there's no need to worry about deadlock issues.

✨ Features

What is PyRunner MCP?

PyRunner MCP is a Model Context Protocol (MCP) Server that enables AI assistants (such as Gemini CLI) to:

• Execute Python code: Run in a persistent kernel, with variables retained across multiple executions.
• Manage Python packages: Quickly check and automatically install dependencies.
• Semantically search scripts: Find previously written scripts using descriptions and tags.
• Long-term memory: Remember your preferences, project background, and frequently used commands.
• Execute Shell commands: Git clone, pip install, system commands.

Core Feature: Persistent Kernel

It offers a Jupyter Notebook-like experience, but in the command line:

• Load a 10GB DataFrame once, and subsequent analyses don't require re-reading.
• Import large packages (pandas, torch) once, and subsequent executions start instantly.
• Variables, functions, and classes persist.

Why is this needed?

AI tools in 2025 are already very powerful

So, what's the value of PyRunner MCP?

Core Difference: Persistent Kernel

┌─────────────────────────────────────────────────────────────┐
│  Gemini CLI / Copilot          PyRunner MCP                 │
│  ─────────────────────          ────────────                │
│  Each execution = new process    Variables retained across executions │
│                                                             │
│  x = 100  ──Execute──►  x disappears   x = 100  ──Execute──►  x still exists │
│  print(x) ──Execute──►   Error       print(x) ──Execute──►   100     │
└─────────────────────────────────────────────────────────────┘

Feature Comparison

Unique Advantages

1. stdout/stderr redirection (no blocking)

Problem: When executing long-running tasks such as SSH connections, ping monitoring, and web crawling, native tools may get stuck due to a full pipe buffer.

PyRunner Solution:

# Output is automatically redirected to files, no blocking
stdout → temp/stdout.txt
stderr → temp/stderr.txt

Applicable scenarios:

• SSH remote execution (netmiko, paramiko)
• Network monitoring (ping, traceroute)
• Web crawling tasks with large outputs
• Loop tasks and daemons

2. Ultra-fast package checking (microsecond level)

# Check directly within the MCP process without starting a subprocess
check_packages("pandas numpy torch")
# ✓ Installed: pandas, numpy
# ✗ Not installed: torch

3. Memory system (structured JSON)

remember("User preference for Black formatting", category="preference")
remember("Project X's API: https://api.x.com", category="project")

recall("API")  # Search for relevant memories only

4. Shell command purification environment

run_shell("git clone https://github.com/xxx/yyy")

Automatic handling:

• GIT_TERMINAL_PROMPT=0 (disable interactive prompts)
• GIT_LFS_SKIP_SMUDGE=1 (skip large files)
• Unified working directory (BASE_DIR)

Suitable Scenarios

Suitable for PyRunner MCP

• Data analysis: Read a 10GB CSV once, and subsequent analyses don't require re-reading.
• Machine learning: Load a model once and repeatedly test inferences.
• Interactive development: A CLI experience similar to Jupyter Notebook.
• Large number of independent scripts: Manage and search using metadata.

Not suitable (better to use native tools)

• Full project development (with src/, tests/ structure) → Copilot @workspace
• Team collaboration, PR review, CI/CD → GitHub Copilot Workspace
• Multi-language projects → Native Gemini CLI

💻 Usage Examples

Persistent Kernel

# First execution
You: Load sales.csv
AI: save_and_run("load.py", "import pandas as pd; df = pd.read_csv('sales.csv')", use_kernel=True)
✓ Success

# Second execution (df still exists!)
You: Show the first 5 rows
AI: save_and_run("show.py", "print(df.head())", use_kernel=True)
✓ [Show DataFrame]

# No need to re-read the CSV!

Kernel Management Tools

# Check status
kernel_status()
# 🟢 KERNEL Status
# ├─ Running time: 15 minutes 32 seconds
# ├─ Number of variables: 8
# └─ Memory usage: 45.2 MB

# Inspect variables
inspect_kernel_vars()
# 📦 KERNEL Variables (3 in total)
# ├─ df (DataFrame, 15.2 MB)
# ├─ model (Sequential, 102.5 MB)
# └─ config (dict, 1.2 KB)

# Reset
reset_kernel()
# 🔄 Kernel has been reset, all variables have been cleared

Semantic Search

search_workspace("PTT crawler")
# → fetch_ptt.py (Relevance:4) [crawler, ptt]
#   Crawl the latest articles on the PTT Gossiping board

📚 Documentation

Complete Tool List

Project Structure

PyRunner_MCP/
├── PyRunner_MCP.py       # Main program of the MCP Server
├── kernel_server.py      # Persistent Kernel process
├── GEMINI.md             # AI behavior guide
├── workspace/            # Script storage area
│   ├── *.py              # Python scripts
│   └── *.meta.json       # Metadata (for search)
├── temp/                 # Temporary storage (stdout/stderr)
└── memory.json           # Long-term memory