MCP Code Mode 🐍⚡

Universal Python code execution MCP server - one tool to rule them all.

Inspired by Cloudflare's Code Mode: LLMs are better at writing code than making tool calls because they've trained on millions of real repositories.

Why Code Mode?

Traditional approach (many tools):

User: "Get weather for Austin and save to file"

LLM: [tool_call: get_weather(location="Austin")]
     → waits for response...
LLM: [tool_call: write_file(path="weather.txt", content=...)]
     → waits for response...

Code Mode approach (one tool):

User: "Get weather for Austin and save to file"

LLM: [run_python]
import requests
weather = requests.get("https://wttr.in/Austin?format=j1").json()
temp = weather['current_condition'][0]['temp_F']
with open("weather.txt", "w") as f:
    f.write(f"Austin: {temp}°F")
print(f"Saved! Temperature: {temp}°F")

Benefits

Traditional Tools	Code Mode
❌ LLMs struggle with synthetic tool-call format	✅ LLMs excel at writing real code
❌ Each tool call = round trip to LLM	✅ Complex workflows in one execution
❌ Managing 20+ extensions	✅ One universal tool
❌ Token waste passing data between calls	✅ Efficient data flow in code
❌ Limited to pre-built capabilities	✅ Anything Python can do

Works With Any MCP Client

✅ Goose (Block's AI agent)
✅ Claude Desktop
✅ Cursor
✅ VS Code with Copilot
✅ Any MCP-compatible agent

Features

🚀 Universal Execution

Write Python to accomplish any task - HTTP requests, file operations, data processing, web scraping, image manipulation, and more.

📦 Auto-Install Dependencies

Missing a package? Code Mode detects ModuleNotFoundError, installs the package, and retries automatically.

🌊 Streaming Output

See results in real-time! run_python_stream shows output line-by-line as your code executes. Perfect for long-running tasks, progress bars, and monitoring live operations.

🖼️ Automatic File Display (Goose Compatible!)

Generated images, logs, or data files? Code Mode automatically detects and displays them in your MCP client! Supports:

Images: PNG, JPG, GIF, SVG, HEIC, TIFF, etc. (displayed inline)
Text Files: JSON, logs, source code (Python, JS, TS, Go, Rust, etc.), CSV, YAML, etc. (shown with syntax highlighting)
Resources: PDFs, archives, videos (MP4, MOV), audio (MP3, WAV), Office docs, databases (available for download)

Just print the file path and Code Mode handles the rest! Works seamlessly with Goose and other MCP clients.

🧠 Dual Learning System (Enhanced!)

Records both error-based and semantic failures:

Error Learning: Captures errors (ModuleNotFoundError, SSL errors, etc.) and their solutions
Semantic Learning: Learns when code runs successfully but doesn't accomplish the objective

Future executions benefit from past learnings. Persists across sessions.

🔄 Intelligent Retry

run_with_retry analyzes failures and suggests fixes based on both error patterns and semantic learnings from similar tasks.

🐳 Optional Docker Sandbox

Run code in isolated Docker containers for enhanced security.

⚙️ Configurable

Adjust timeouts, execution modes, package restrictions, and more.

Installation

From PyPI (when published)

# Using uv (recommended)
uv tool install mcp-pyrunner

# Using pip
pip install mcp-pyrunner

From Source

git clone https://github.com/anaseqal/codemode.git
cd codemode
uv sync

Configuration

Goose

If installed from PyPI:

Edit ~/.config/goose/config.yaml:

extensions:
  codemode:
    type: stdio
    enabled: true
    cmd: uvx
    args: ["mcp-pyrunner"]

If running from source (local development):

extensions:
  codemode:
    type: stdio
    enabled: true
    cmd: uv
    args: ["run", "--directory", "/path/to/codemode", "mcp-pyrunner"]
    # Replace /path/to/codemode with actual path (e.g., ~/codemode)

Or use the UI: Extensions → Add Custom Extension → STDIO → Command: uv run --directory /path/to/codemode mcp-pyrunner

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

If installed from PyPI:

{
  "mcpServers": {
    "codemode": {
      "command": "uvx",
      "args": ["mcp-pyrunner"]
    }
  }
}

If running from source:

{
  "mcpServers": {
    "codemode": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codemode", "mcp-pyrunner"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

If installed from PyPI:

{
  "mcpServers": {
    "codemode": {
      "command": "uvx",
      "args": ["mcp-pyrunner"]
    }
  }
}

If running from source:

{
  "mcpServers": {
    "codemode": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codemode", "mcp-pyrunner"]
    }
  }
}

Available Tools

Tool	Description
`get_system_context`	Get environment info (OS, Python, pip versions, package managers, learnings)
`run_python`	Execute Python code (auto-installs packages, auto-displays files)
`run_python_stream`	Execute with real-time streaming output (auto-displays files)
`run_with_retry`	Execute with intelligent retry, error analysis, and semantic learning suggestions
`add_learning`	Record error-based solutions for future reference
`record_semantic_failure`	NEW! Record when code runs but doesn't accomplish objective
`get_learnings`	View/search past learnings (both error and semantic)
`pip_install`	Pre-install a specific package
`configure`	View/update settings

Usage Examples

Web Scraping

User: "Scrape the top 10 posts from Hacker News"

→ run_python:
import requests
from bs4 import BeautifulSoup

resp = requests.get("https://news.ycombinator.com")
soup = BeautifulSoup(resp.text, "html.parser")

for i, item in enumerate(soup.select(".titleline > a")[:10], 1):
    print(f"{i}. {item.text}")
    print(f"   {item['href']}\n")

Data Processing

User: "Analyze sales.csv and show monthly totals"

→ run_python:
import pandas as pd

df = pd.read_csv("sales.csv")
df["date"] = pd.to_datetime(df["date"])
monthly = df.groupby(df["date"].dt.to_period("M"))["amount"].sum()

print("Monthly Sales:")
for period, total in monthly.items():
    print(f"  {period}: ${total:,.2f}")

API Integration

User: "Get the current Bitcoin price in USD"

→ run_python:
import requests

data = requests.get("https://api.coinbase.com/v2/prices/BTC-USD/spot").json()
price = float(data["data"]["amount"])
print(f"Bitcoin: ${price:,.2f} USD")

Image Processing

User: "Resize all images in ./photos to 800x600"

→ run_python:
from pathlib import Path
from PIL import Image

photos = Path("./photos")
for img_path in photos.glob("*.jpg"):
    img = Image.open(img_path)
    img.thumbnail((800, 600))
    img.save(img_path)
    print(f"Resized: {img_path.name}")

Streaming Output (Real-Time Progress)

User: "Scrape top 20 HN posts with progress updates"

→ run_python_stream:
import requests
from bs4 import BeautifulSoup
import time

print("🔍 Starting to scrape Hacker News...")

resp = requests.get("https://news.ycombinator.com")
soup = BeautifulSoup(resp.text, "html.parser")
stories = soup.select(".titleline > a")[:20]

print(f"📊 Found {len(stories)} stories. Processing...\n")

for i, story in enumerate(stories, 1):
    # Show progress in real-time
    progress = "█" * i + "░" * (20 - i)
    print(f"[{progress}] {i}/20: {story.text}")
    time.sleep(0.5)  # See each item appear live!

print("\n✅ Scraping complete!")

# Output appears LINE BY LINE as the code runs,
# not all at once at the end!

Automatic File Display

User: "Take a screenshot of example.com and create a summary report"

→ run_python:
from playwright.sync_api import sync_playwright
import json

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")

    # Take screenshot
    screenshot_path = "/tmp/example_screenshot.png"
    page.screenshot(path=screenshot_path)

    # Create report
    report = {
        "url": "https://example.com",
        "title": page.title(),
        "screenshot": screenshot_path,
        "timestamp": "2025-01-26T12:00:00"
    }

    report_path = "/tmp/report.json"
    with open(report_path, "w") as f:
        json.dump(report, f, indent=2)

    browser.close()

    # Print file paths - Code Mode auto-detects and displays them!
    print(f"Screenshot saved to: {screenshot_path}")
    print(f"Report saved to: {report_path}")

# Result: Your MCP client displays the screenshot IMAGE inline
# and shows the JSON content formatted - no manual handling needed!

Configuration Options

View current config:

→ configure()

Update settings:

→ configure(action="set", key="execution_mode", value="docker")
→ configure(action="set", key="default_timeout", value="120")

Setting	Values	Description
`execution_mode`	`direct`, `docker`	How to run code
`default_timeout`	integer	Default timeout (seconds)
`max_retries`	integer	Default retry attempts
`auto_install`	`true`, `false`	Auto-install packages
`docker_image`	string	Docker image for sandbox

Dual Learning System

Code Mode learns from two types of failures:

1. Error-Based Learning

When you solve an error, record it:

→ add_learning(
    error_pattern="SSL: CERTIFICATE_VERIFY_FAILED",
    solution="Use verify=False or install/update certifi",
    context="HTTPS requests on systems with cert issues",
    tags="ssl,https,certificates"
)

2. Semantic Learning (NEW!)

When code runs successfully but doesn't accomplish the objective:

→ record_semantic_failure(
    objective="Display image in Goose app",
    failed_approach="Used print() to output file path",
    successful_approach="Returned base64 encoded image as MCP content object",
    context="MCP clients need structured content objects, not just paths",
    tags="goose,mcp,display,images"
)

Why semantic learning matters:

Code executed without errors ≠ objective accomplished
AI learns from "technically correct but semantically wrong" approaches
Future attempts at similar objectives benefit from past semantic learnings

View Learnings

→ get_learnings()              # View all learnings (error + semantic)
→ get_learnings(search="ssl")  # Search learnings

Learnings are distinguished by icons:

🔴 Error-based learnings
🔵 Semantic learnings

Learnings persist in ~/.mcp-pyrunner/learnings.json and improve future executions.

Data Storage

Code Mode stores data in ~/.mcp-pyrunner/:

~/.mcp-pyrunner/
├── config.json       # User configuration
├── learnings.json    # Error patterns and solutions
└── execution_log.json # Recent execution history

Security Considerations

⚠️ Code Mode executes arbitrary Python code.

Direct mode (default):

Code runs with your user permissions
Full filesystem and network access
Fast execution

Docker mode (more secure):

Code runs in isolated container
Limited resources (512MB RAM, 1 CPU)
Network access available
Slower startup

Enable Docker mode:

→ configure(action="set", key="execution_mode", value="docker")

Testing

# Run tests
uv run pytest

# Test with MCP Inspector
uv run mcp dev src/mcp_codemode/server.py
# Open http://localhost:5173

Contributing

Contributions welcome! Areas of interest:

~~Streaming output for long-running code~~ ✅ DONE!
~~Automatic file display (images, text, resources)~~ ✅ DONE!
~~Enhanced system context (pip version, package managers)~~ ✅ DONE!
Vector DB for semantic learning search
Pyodide/WASM sandboxing option
Code analysis before execution
Resource usage tracking
Multi-file project support

License

MIT

Acknowledgments

Cloudflare's Code Mode for the inspiration
Model Context Protocol for the standard
Block's Goose for being an excellent MCP client

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
src		src
tests		tests
.DS_Store		.DS_Store
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
setup.sh		setup.sh
test_auto_learning.py		test_auto_learning.py
test_streaming.py		test_streaming.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

MCP Code Mode 🐍⚡

Why Code Mode?

Benefits

Works With Any MCP Client

Features

🚀 Universal Execution

📦 Auto-Install Dependencies

🌊 Streaming Output

🖼️ Automatic File Display (Goose Compatible!)

🧠 Dual Learning System (Enhanced!)

🔄 Intelligent Retry

🐳 Optional Docker Sandbox

⚙️ Configurable

Installation

From PyPI (when published)

From Source

Configuration

Goose

Claude Desktop

Cursor

Available Tools

Usage Examples

Web Scraping

Data Processing

API Integration

Image Processing

Streaming Output (Real-Time Progress)

Automatic File Display

Configuration Options

Dual Learning System

1. Error-Based Learning

2. Semantic Learning (NEW!)

View Learnings

Data Storage

Security Considerations

Testing

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages