ScratchRun
Ephemeral MicroVM-isolated code execution for AI agents. Fresh VM per call, hard-purged after.
Open source Open in the app JSON README (API)
About
Ephemeral MicroVM-isolated code execution for AI agents. Fresh VM per call, hard-purged after.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- dev.scratchrun
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-08-04T20:48:43Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-29 03:01:31
- Updated
- 2026-08-29 03:01:31
- Origin id
dev.scratchrun/mcp
README
# @scratchrun/mcp-server
MCP server for [ScratchRun](https://scratchrun.dev) — 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`:
```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](https://scratchrun.dev).
## Tool: `scratchrun_exec`
Executes code in an ephemeral sandbox and returns stdout, stderr, exit code, and any output files.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `runtime` | `python3.12` \| `python3.11` \| `node20` \| `bash` | yes | Runtime to use |
| `code` | string | yes | Code to execute |
| `timeout_ms` | integer | no | Timeout in ms (default 10000, max 30000) |
| `memory_mb` | integer | no | Memory limit in MB (default 256, max 512) |
| `env` | object | no | Environment variables — use for secrets, not code strings |
| `files` | object | no | Files to write before execution (path → content) |
| `return_files` | string[] | no | File paths to capture after execution (returned as base64) |
**Example — run Python and return a chart:**
```json
{
"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