How do I use MCP Code Mode?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Code Mode fetch weather data for Tokyo and save as JSON" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Code Mode

by anaseqal

Overview Schema Source Related Servers Discussions Admin

Python

Local

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

Related MCP server: MCP Server

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

Available Tools

9 tools

add_learningA

Record a learning from a code execution for future reference.

When you figure out how to fix an error, record it here. Future executions will suggest this solution for similar errors.

Args: error_pattern: Text/regex that matches the error message solution: What fixed the problem context: When this solution applies tags: Comma-separated tags (e.g., "network,ssl,https")

Example: add_learning( error_pattern="SSL: CERTIFICATE_VERIFY_FAILED", solution="Add verify=False to requests.get() or install certifi", context="HTTPS requests on systems with certificate issues", tags="ssl,https,certificates" )

Returns: Confirmation message

Inputs: error_pattern (required), solution (required), context (required), tags. Returns: result

configureA

View or update Code Mode configuration.

Args: action: "view" to see config, "set" to update a value key: Config key to update (for action="set") value: New value (for action="set")

Available settings:

execution_mode: "direct" (fast) or "docker" (secure sandbox)
default_timeout: Default execution timeout in seconds
max_retries: Default max retry attempts
auto_install: Whether to auto-install packages (true/false)
docker_image: Docker image for sandbox mode

Examples: configure() # View current config configure(action="set", key="execution_mode", value="docker") configure(action="set", key="default_timeout", value="120")

Returns: Current configuration or update confirmation

Inputs: action, key, value. Returns: result

get_learningsA

View recorded learnings from past executions.

Args: search: Optional search term to filter learnings

Returns: Summary of learnings, optionally filtered

Inputs: search. Returns: result

get_system_contextA

Get comprehensive system context before writing code.

CALL THIS FIRST to understand:

OS, Python version, available paths
Installed and available libraries
Execution mode (direct or Docker sandbox)
Past learnings from errors
Tips for writing effective code

Returns detailed system information formatted for code generation.

Inputs: no named parameters. Returns: result

pip_installA

Pre-install a Python package.

Use this to install packages before execution if you know you'll need them, or if auto-install missed something.

Args: package_name: The pip package name to install

Returns: Installation result

Inputs: package_name (required). Returns: result

record_semantic_failureA

Record a semantic failure: when code executed successfully but didn't accomplish the goal.

This is different from error-based learning. Use this when:

Code ran without errors but produced wrong output
Tool was used but didn't achieve the intended objective
An approach worked technically but failed semantically

Args: objective: What you were trying to accomplish failed_approach: What you tried that didn't work (even though it ran) successful_approach: What actually worked to accomplish the objective context: Why the first approach failed or additional context tags: Comma-separated tags (e.g., "api,authentication,retry")

Example: 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" )

Returns: Confirmation message

Inputs: objective (required), failed_approach (required), successful_approach (required), context, +1 more. Returns: result

run_pythonA

Execute Python code to accomplish ANY task.

This is a universal tool - write Python to do what you need:

HTTP requests (requests, httpx, aiohttp)
Parse HTML (beautifulsoup4, lxml)
Process data (pandas, json, csv)
File operations (pathlib, shutil)
System commands (subprocess)
Images (Pillow, opencv)
And anything else Python can do!

Args: code: Python code to execute. Use print() for output. description: Brief task description (for logging) timeout: Max execution time in seconds auto_install: Auto-install missing packages

Returns: Execution result with stdout, stderr, status, and any generated images

Example: code = ''' import requests resp = requests.get("https://api.github.com/users/octocat") data = resp.json() print(f"User: {data['login']}") print(f"Repos: {data['public_repos']}") '''

Inputs: code (required), description, timeout, auto_install.

run_python_streamA

Execute Python code with REAL-TIME STREAMING OUTPUT.

Perfect for long-running tasks where you want to see progress as it happens:

Web scraping multiple pages (see each page as it's scraped)
Data processing loops (see progress through large datasets)
API calls with retries (see each attempt)
File operations (see each file as it's processed)
Long computations (see intermediate results)

Output streams in real-time as the code executes, so you see results immediately instead of waiting for the entire execution to complete.

Args: code: Python code to execute. Use print() liberally for progress updates. description: Brief task description (for logging) timeout: Max execution time in seconds auto_install: Auto-install missing packages

Returns: Streaming output followed by execution summary, with any generated images

Example: code = ''' import time for i in range(5): print(f"Processing item {i+1}/5...") time.sleep(1) print("✓ Done!") '''

The output will appear line-by-line as the code runs, not all at once at the end.

Inputs: code (required), description, timeout, auto_install.

run_with_retryA

Execute Python code with intelligent retry and error analysis.

On failure, this tool:

Analyzes the error pattern
Searches past learnings (both error-based and semantic) for solutions
Provides diagnostic information
Suggests fixes based on error type and similar objectives

IMPORTANT: Use record_semantic_failure() if code runs successfully but doesn't accomplish the objective. This helps the system learn from non-error failures.

Use this for more robust execution when errors are expected or when learning from previous similar tasks.

Args: code: Python code to execute description: Task description (helps find relevant semantic learnings) max_retries: Max retry attempts (same code) timeout: Execution timeout in seconds

Returns: Detailed execution result with retry info and suggestions from both error and semantic learnings

Inputs: code (required), description, max_retries, timeout. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-05-29 23:25 across 9 tools

Disambiguation5/5

Each tool has a clear and distinct purpose. run_python and run_python_stream are differentiated by streaming vs. non-streaming execution. run_with_retry adds retry logic. Learning tools (add_learning, record_semantic_failure) handle different failure types. configure, get_learnings, get_system_context, and pip_install are all unique and unambiguous.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case, e.g., add_learning, run_python, get_system_context. There are no deviations or mixed conventions.

Tool Count5/5

With 9 tools, the set is well-scoped for a code execution MCP server. It covers execution, learning, configuration, context retrieval, and package management without redundancy or gaps.

Completeness4/5

The tool surface covers core workflows: code execution (with variants), error/semantic learning, configuration, system context, and package installation. Minor gaps exist (e.g., no tool to delete or update learnings), but overall it's nearly complete for the stated purpose.

Resources

Related MCP Connectors

SubstrateB
co.trysubstrate
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Developer Tools Knowledge & Memory
131
https://app.trysubstrate.co/mcp
mcp-aichat
io.github.AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
AI & Machine Learning
2
https://aichat.mcp.acedata.cloud/mcp
docs
dev.continue
An MCP server for docs.continue.dev
Documentation Access Developer Tools Search
2
https://docs.continue.dev/mcp
mcp-server
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
https://mcp.niftypm.com/mcp

Related MCP Servers

Sandbox MCP
Code Execution Virtualization
pottekkat
A
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server that enables LLMs to run ANY code safely in isolated Docker containers.
Updated a year ago (2025-05-13 11:32 UTC)
124
MIT
MCP Server
File Systems Web Scraping Shell Access
kennetchau
A
license
Not graded
quality
D
maintenance
A modular MCP server providing file operations, web search, URL scraping, and sandboxed command execution for LLM interactions.
Updated 6 months ago (2026-05-16 16:57 UTC)
1
MIT
mcp-toolbox
Developer Tools Command Line Design Tools
fastmcp-me
A
license
Not graded
quality
D
maintenance
A comprehensive MCP server enabling LLMs to execute commands, manage files, interact with Figma, search the web, generate images, and more, extending their capabilities beyond text generation.
Updated a year ago (2025-10-02 20:19 UTC)
Apache 2.0
mcp-python-repl
Code Execution Command Line
aazizisoufiane
A
license
A
quality
D
maintenance
A production-grade MCP server providing a persistent Python REPL with multi-session support, sandboxing, and timeout protection, enabling LLM agents to execute Python code across multiple turns with variables that persist between calls.
Updated 9 months ago (2026-02-11 15:31 UTC)
12
31 PyPI
1
MIT

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

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

Sandbox MCP

MCP Server

mcp-toolbox

mcp-python-repl