mcpField
S
ScratchRun

ScratchRun

Local
github.com/ar-bluesDeveloper Tools0Updated 13w ago
Repository

About ScratchRun

ScratchRun is an MCP server for AI agents that runs code in fresh, hardware-isolated MicroVMs and destroys each VM after execution. It supports Python, Node.js, and Bash, with no files or state retained between calls.

Key features

  1. 01Fresh MicroVM for each run
  2. 02Python, Node.js, and Bash runtimes
  3. 03Configurable time and memory limits
  4. 04Input and output file handling
  5. 05Network access blocks private and metadata IPs

Use cases

  1. 01Run agent-generated code in an isolated environment
  2. 02Generate charts and retrieve image files
  3. 03Execute scripts without carrying state across runs

MCP support

Exposes the `scratchrun_exec` tool to MCP clients for code execution. Results include stdout, stderr, exit code, and requested output files; images can be returned as MCP image content.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "dev-scratchrun": {
      "command": "npx",
      "args": [
        "-y",
        "@scratchrun/mcp-server"
      ],
      "env": {
        "SCRATCHRUN_API_KEY": "<SCRATCHRUN_API_KEY>"
      }
    }
  }
}
Run commandnpx -y @scratchrun/mcp-server
Environment variables to set
SCRATCHRUN_API_KEYSecretScratchRun API key — get one at https://scratchrun.dev

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@scratchrun/mcp-server0.1.1

Tools

1

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
envobjectNoEnvironment variables injected into the sandbox. Use for secrets and config.
codestringYesCode to execute.
filesobjectNoFiles to write before execution. Keys are absolute paths, values are file contents.
runtimeenumYesRuntime. python3.12 includes numpy, pandas, matplotlib, requests, and more.python3.12 | python3.11 | node20 | bash
memory_mbintegerNoMemory limit in MB.
timeout_msintegerNoExecution timeout in milliseconds. Exit code 124 signals timeout.
return_filesarrayNoFile paths to capture after execution and return as base64. Use for charts, CSVs, or any output artifact.

Details

From the project README

@scratchrun/mcp-server

MCP server for ScratchRun — ephemeral, MicroVM-isolated code execution for AI agents.

Each call runs in a fresh hardware-isolated MicroVM. The VM is hard-purged after execution. No state, no files, nothing persists between calls.

Install

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "scratchrun": {
      "command": "npx",
      "args": ["-y", "@scratchrun/mcp-server"],
      "env": {
        "SCRATCHRUN_API_KEY": "sr_live_your_key_here"
      }
    }
  }
}

Get an API key at scratchrun.dev.

Tool: scratchrun_exec

Executes code in an ephemeral sandbox and returns stdout, stderr, exit code, and any output files.

Parameters:

ParameterTypeRequiredDescription
runtimepython3.12 | python3.11 | node20 | bashyesRuntime to use
codestringyesCode to execute
timeout_msintegernoTimeout in ms (default 10000, max 30000)
memory_mbintegernoMemory limit in MB (default 256, max 512)
envobjectnoEnvironment variables — use for secrets, not code strings
filesobjectnoFiles to write before execution (path → content)
return_filesstring[]noFile paths to capture after execution (returned as base64)

Example — run Python and return a chart:

{
  "runtime": "python3.12",
  "code": "import matplotlib.pyplot as plt\nimport numpy as np\nx = np.linspace(0, 10, 100)\nplt.plot(x, np.sin(x))\nplt.savefig('/tmp/plot.png')",
  "return_files": ["/tmp/plot.png"]
}

Output files are returned as base64. Image files (PNG, JPG, SVG) are returned as MCP image content blocks and render inline in Claude.

Isolation

  • Hardware-virtualized MicroVM per execution (own kernel, not a shared-kernel container)
  • TerminateMicroVM called unconditionally after every run — VM destroyed, never reused
  • RFC 1918 + cloud metadata (169.254.x.x) always blocked at the network layer
  • Read-only system filesystem via OverlayFS; /tmp is RAM-backed and gone with the VM

Latency

~400ms median (warm pool). 2–8s cold start if the pool is empty.

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.