Skip to main content
Glama

scratch-mcp

A Model Context Protocol server for editing Scratch .sb3 projects, built on scratch4js. It keeps one project open in memory, exposes the library's editing surface as MCP tools, and saves back to disk.

It also hosts a live-reload bridge on http://localhost:9060. With the TurboWarp Desktop userscript installed, every save_project reloads the project live in the editor — so an agent's edits appear instantly.

Install

npx scratch-mcp     # serves MCP over stdio

Related MCP server: scratch-mcp

Develop

The MCP server lives at the repo root; the libraries it builds on are workspace packages under packages/.

pnpm install
pnpm run build   # builds scratch4js, s-api4js and the userscript
pnpm start       # serves MCP over stdio

Configure an MCP client

{
  "mcpServers": {
    "scratch": {
      "command": "node",
      "args": ["/abs/path/to/ScratchMCP/src/index.js"]
    }
  }
}

Set SCRATCH_MCP_BRIDGE_PORT to change the bridge port (default 9060). If the port is taken the server still starts; only live reload is disabled.

Install as an MCP Bundle (.mcpb)

For one-click installation in Claude Desktop and other MCPB-aware clients, this server packages as an MCP Bundle — a single .mcpb file containing the server plus a self-contained node_modules.

pnpm run mcpb   # → dist/scratch-mcp-<version>.mcpb

Then open the .mcpb in your client (in Claude Desktop, drag it into Settings → Extensions). The bundle exposes one setting — the live-reload bridge port — and needs no other configuration. The build (scripts/build-mcpb.mjs) vendors the scratch4js and s-api4js workspace packages as tarballs and installs the git scratch-vm and its peers into a flat node_modules, as MCPB requires. The manifest.json is the bundle's source of truth (its version is stamped from package.json at build time).

Tools

Project

  • open_project { path } — load an .sb3 into memory.

  • save_project { path?, compressionLevel? } — write it back (and live-reload).

  • project_info — targets, extensions, monitors, meta.

Scratch website (online projects, via s-api4js)

  • scratch_login { username?, password? } — log in to scratch.mit.edu (defaults to $SCRATCH_USER / $SCRATCH_PASS). The session lives in memory for the server process only.

  • open_scratch_project { projectId } — download a project by id and open it for editing (shared projects need no login; your own unshared ones do).

  • push_to_scratch { projectId?, confirm? } — save the open project back to scratch.mit.edu, overwriting it online (uploads assets, then project.json).

  • share_project { projectId?, confirm? } — publish a project so it's public.

push_to_scratch and share_project change the live project, so they always ask you to confirm first — via an MCP elicitation prompt when your client supports it, otherwise by requiring confirm: true (which the agent should only set after you've agreed).

Reading

  • list_sprites — every sprite with position/size/media.

  • get_target { name } — full details for a sprite or "Stage".

  • get_target_json { name, pointer? } — the target's raw project.json entry (blocks, costumes, sounds, …), or a subtree at a JSON Pointer. Read this before authoring a patch_target.

Block reference (so the agent knows which blocks exist and how to fill them)

  • list_blocks { category? } — the catalog of standard opcodes, each with its category, shape (hat / stack / c-block / cap / reporter / boolean) and the names of its inputs and fields. Generated at startup from the installed scratch-vm, so it stays in sync.

  • get_block_schema { opcode, target? } — full schema for one opcode: every input with its sb3 shadow encoding (e.g. a text input is [1, [10, "hi"]]), every field with enumerated dropdown options, and a ready-to-adapt example block JSON. Dynamic menu options (sprites, sounds, costumes, broadcasts, …) are filled from the open project; pass target to enumerate that sprite's own costumes and sounds. Covers built-in extension blocks too (pen_*, music_*, microbit_*, …), generated from each extension's getInfo().

Extensions

  • enable_extension { id, url? } — register an extension so its blocks load and show in the palette (required before using any <id>_… block). Pass just id for a built-in (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor); add url for a custom/third-party (TurboWarp) extension. list_blocks { category: "<id>" } and get_block_schema describe built-in extension blocks; patch_target warns when a block uses an extension that isn't enabled. Custom extensions are opaque — mirror an existing block via get_target_json.

Editing raw JSON (diff/patch)

  • patch_target { name, patch } — apply an RFC 6902 JSON Patch to a target's raw JSON. This is how you edit a sprite's scripts (blocks) or any field the higher-level tools don't cover — on a sprite you just created or an existing one. Paths are JSON Pointers into get_target_json; the patch applies atomically (all-or-nothing) and the result reports advisory warnings for unknown opcodes or inputs. Patching costumes/sounds arrays doesn't move asset bytes — use add_costume/remove_costume for that.

Sprites & stage

  • set_sprite { name, x?, y?, size?, direction?, visible?, draggable?, rotationStyle?, layerOrder?, volume? }

  • add_sprite { name, ...props } / remove_sprite { name } / rename_target { name, newName }

  • set_stage { tempo?, videoState?, videoTransparency?, volume? }

Variables, lists, broadcasts (target is a sprite name or "Stage")

  • set_variable { target, name, value } / delete_variable { target, name }

  • set_list { target, name, items } / delete_list { target, name }

  • add_broadcast { name }

Costumes & sounds

  • add_costume { target, name, path, dataFormat?, rotationCenterX?, rotationCenterY? }

  • remove_costume { target, name }

  • add_sound { target, name, path, dataFormat? } / remove_sound { target, name }

Run & test (headless TurboWarp VM, in-process)

  • vm_load — load the open project into a headless VM (reflects in-memory edits).

  • vm_green_flag — press the green flag (clears bubbles, question, errors).

  • vm_run { seconds?, frames?, untilIdle?, paced? } — advance the VM, then return state plus an events timeline (say/think, broadcasts, question/answer, errors) since the last run.

  • vm_state — snapshot: every target's position/size/direction/costume/visibility, variables, lists, monitors, say/think bubbles, pending question, running threads, errors.

  • vm_input { keys?, mouseX?, mouseY?, mouseDown?, answer? } — feed keyboard/mouse input and answer ask and wait.

  • vm_stop — stop all scripts.

Live reload & screenshots (require the bridge + userscript)

  • reload { path? } — load an .sb3 from disk in the editor.

  • run_project / stop_project — green flag / stop.

  • screenshot — capture the live stage as a lossless PNG, for when exact pixels matter. Takes no parameters.

  • screenshot_jpeg { quality? } — the same capture re-encoded as a compressed JPEG (smaller, cheaper to read; quality 1–100, default 80).

Running and testing a project

The vm_* tools embed TurboWarp's scratch-vm (the JIT fork) in this process — no browser, no WebGL. The loop is: edit → vm_load → vm_green_flag → vm_run → read vm_state → assert. It returns structured state (variable values, sprite positions, say bubbles), which an agent can assert against directly — far better than reasoning over pixels, and deterministic enough for CI.

The headless VM has no renderer or audio: costume metadata still loads (so costume-by-name/number logic works), but renderer-backed blocks (touching colour/sprite/edge, pen) and sound playback are inert. To see the real rendered stage, run the project in TurboWarp Desktop and call screenshot.

Events

Notable events — say/think, broadcast, greenflag, stop, question/answer and runtime/compile errors, each { level, type, message, …fields } — are surfaced two ways:

  • In vm_run's result (events): the ordered timeline since the previous vm_run. This is the agent-facing channel — the model reads it directly in the tool result and can assert on sequence, not just final state. Always on.

  • As MCP log notifications (notifications/message, logger: "scratch-vm"): the client/human-facing channel for a host's log view. Off until the client raises its log level via logging/setLevel — "info" for activity, "debug" to also include run boundaries and bubble-clears, "warning"+ for errors only. (Most clients don't feed notifications back to the model, which is why the vm_run channel exists.)

Repeated identical say/think bubbles are de-duplicated so a say in a loop doesn't flood either channel.

How live reload works

The bridge is a plain WebSocket + HTTP server. The userscript connects over WebSocket and answers JSON requests (loadSB3 / start / stop / screenshot). On loadSB3 it fetches the bytes from GET /get.sb3?path=… and loads them into the TurboWarp VM; save_project writes the file then sends loadSB3, so the editor always shows the latest save. A snapshot comes back as a PNG, which the server passes through unchanged (screenshot) or re-encodes as a compressed JPEG (screenshot_jpeg).

Available Tools

43 tools
add_broadcastAdd broadcastA

Add a broadcast message to the project (no-op if it already exists).

Inputs: name (required).

add_commentAdd commentA

Add a workspace comment to a target. With no blockId the comment floats free on the canvas; pass a blockId (a key in the target's blocks map — see get_target_json) to attach it to that block, which also sets the block's comment back-reference so the editor anchors it.

Inputs: text (required), target (required), x, y, +4 more.

add_costumeAdd costumeB

Add a costume to a sprite (or the stage) from an image file on disk.

Inputs: name (required), path (required), target (required), dataFormat, +2 more.

add_soundAdd soundB

Add a sound to a sprite (or the stage) from an audio file on disk.

Inputs: name (required), path (required), target (required), dataFormat.

add_spriteAdd spriteA

Add a new, empty sprite. Add at least one costume before opening it in the editor.

Inputs: name (required), x, y, size, +6 more.

delete_listDelete listC

Delete a list from a target by name.

Inputs: name (required), target (required).

delete_variableDelete variableA

Delete a variable from a target by name.

Inputs: name (required), target (required).

enable_extensionEnable an extensionA

Register an extension on the project so its blocks load and show in the palette — required before using any <id>_… extension block. For a built-in extension pass just its id (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor). For a custom/third-party (TurboWarp) extension, also pass the loader url so the editor can fetch it. Adds the id to the project's extensions and, with a url, records it in extensionURLs.

Inputs: id (required), url.

get_block_schemaGet block schemaA

The full schema for one block opcode: its shape, every input (with the sb3 shadow encoding to use, e.g. a text input is [1, [10, "hi"]]), every field (with enumerated dropdown options where applicable), and a ready-to-adapt example block JSON. Read this before writing a block with patch_target. In the example, <…> placeholders (block ids, variable ids) must be replaced with real ones; menu inputs also need a matching shadow block (opcode menuOpcode, a field named menuField, shadow: true). Dynamic menu options (sprites, sounds, costumes, …) are filled from the open project; pass target to enumerate that sprite's own costumes and sounds.

Inputs: opcode (required), target.

get_targetGet targetB

Full details for one target (a sprite or the stage), including variables and lists.

Inputs: name (required).

get_target_jsonGet raw target JSONA

A target's complete raw project.json entry — blocks (scripts), costumes, sounds, variables, lists and properties — exactly as stored. Read this first to author a patch_target edit, since the patch paths are JSON Pointers into this object. Pass pointer to fetch just a subtree (e.g. "/blocks" or "/blocks/abc123") and keep the response small.

Inputs: name (required), pointer.

list_blocksList block typesA

The catalog of standard Scratch block opcodes you can use in a target's blocks map — each with its category, shape (hat / stack / c-block / cap / reporter / boolean) and the names of its inputs and fields. Use this to discover opcodes, then get_block_schema for how to fill one in. With no category, lists core blocks; pass a core category (motion, looks, sound, event, control, sensing, operator, data, procedures) or a built-in extension id (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor) to filter.

Inputs: category.

list_commentsList commentsA

List a target's workspace comments — the yellow sticky notes shown in the editor. Each has an id, its text, and either a blockId (when attached to a block) or null (when floating free on the canvas).

Inputs: target (required).

list_spritesList spritesA

List every sprite with its position, size and media.

Inputs: no named parameters.

open_projectOpen projectA

Load an .sb3 file from disk into memory for editing.

Inputs: path (required).

open_scratch_projectOpen a Scratch project from the websiteA

Download a project from scratch.mit.edu by id and hold it open in memory for editing — the same in-memory project the other editing tools act on. Shared projects open without login; your own unshared projects need scratch_login first. Use push_to_scratch to save edits back.

Inputs: projectId (required).

patch_targetPatch target JSONA

Apply an RFC 6902 JSON Patch to a target's raw JSON — the way to edit a sprite's scripts (blocks) or any field a higher-level tool does not cover, on a sprite you just made or an existing one. Paths are JSON Pointers into the object returned by get_target_json; read that first. To write blocks, discover opcodes with list_blocks and get the exact input/field shapes from get_block_schema — the result reports advisory warnings for unknown opcodes or inputs. The patch is applied atomically: if any operation fails the target is left unchanged. Notes: patching the costumes/sounds arrays does not touch stored asset bytes (use add_costume/remove_costume for those), and you are responsible for keeping blocks internally consistent (ids, next/parent links).

Inputs: name (required), patch (required).

project_infoProject infoA

Summarize the open project: targets, extensions, monitors and meta.

Inputs: no named parameters.

push_to_scratchSave edits to the Scratch projectA

Save the open project back to scratch.mit.edu, overwriting the online project's contents (uploads its costumes/sounds, then writes project.json). Requires login and ownership of the project. This edits the live project, so it always asks the user to confirm first (set confirm: true only after the user has agreed).

Inputs: confirm, projectId.

reloadReload in TurboWarpA

Tell connected TurboWarp Desktop userscripts to load an .sb3 from disk (defaults to the open project). Use after editing on disk without going through save_project.

Inputs: path.

remove_commentRemove commentA

Delete a workspace comment from a target by id. If it was attached to a block, the block's comment back-reference is cleared too.

Inputs: id (required), target (required).

remove_costumeRemove costumeB

Remove a costume from a target by name.

Inputs: name (required), target (required).

remove_soundRemove soundC

Remove a sound from a target by name.

Inputs: name (required), target (required).

remove_spriteRemove spriteA

Delete a sprite and any assets only it used.

Inputs: name (required).

rename_targetRename targetB

Rename a sprite (or the stage).

Inputs: name (required), newName (required).

run_projectRun projectB

Press the green flag in connected TurboWarp Desktop userscripts.

Inputs: no named parameters.

save_projectSave projectA

Write the open project back to an .sb3 file (defaults to the path it was opened from). If the TurboWarp Desktop userscript is installed, the editor reloads the file automatically.

Inputs: path, compressionLevel.

scratch_loginLog in to ScratchA

Authenticate with a scratch.mit.edu account so the server can open your projects from the website and (with your confirmation) save edits back and publish them. Credentials default to the SCRATCH_USER / SCRATCH_PASS environment variables if omitted. The session is kept in memory for this server process only.

Inputs: password, username.

screenshotScreenshot the stageA

Capture a PNG of the live stage from a connected TurboWarp Desktop editor (via the live-reload bridge + userscript). This is the real renderer, so load and run the project there first (save_project/run_project). For logic checks prefer vm_state — pixels are a poor substitute for values. For a much smaller payload use screenshot_jpeg.

Inputs: no named parameters.

screenshot_jpegScreenshot the stage (JPEG)A

Same capture as screenshot, but re-encoded as JPEG (via sharp) for a much smaller payload. Prefer this version unless you need pixel fidelity — JPEG is lossy, so fine UI detail and flat color edges may soften. Optional quality (1-100, default 80).

Inputs: quality.

set_commentSet commentA

Update an existing comment on a target by id: its text, position, size, minimized state, or the blockId it is attached to (pass an empty string or null to detach it). Only the fields you pass change.

Inputs: id (required), target (required), x, y, +5 more.

set_listSet listC

Create or replace a list on a target by name.

Inputs: name (required), items (required), target (required).

set_spriteSet sprite propertiesC

Update one or more properties of a sprite (position, size, direction, visibility, …).

Inputs: name (required), x, y, size, +6 more.

set_stageSet stage propertiesC

Update stage-level properties: tempo, video state/transparency, volume.

Inputs: tempo, volume, videoState, videoTransparency.

set_variableSet variableA

Create or update a variable on a target by name.

Inputs: name (required), value (required), target (required).

share_projectPublish (share) the Scratch projectA

Publish a project on scratch.mit.edu so it becomes publicly visible (PUT /proxy/projects//share). Requires login and ownership. Publishing is public and outward-facing, so it always asks the user to confirm first (set confirm: true only after the user has agreed).

Inputs: confirm, projectId.

stop_projectStop projectC

Stop running in connected TurboWarp Desktop userscripts.

Inputs: no named parameters.

vm_green_flagGreen flagA

Press the green flag in the headless runtime (clears bubbles, the pending question and errors, then starts scripts). Does not advance time on its own — call vm_run to step the VM. Run vm_load first.

Inputs: no named parameters.

vm_inputSend inputA

Feed input into the headless VM the way the editor would: key presses, mouse position/clicks, and answers to ask and wait. Stage coordinates run -240..240 (x) and -180..180 (y).

Inputs: keys, answer, mouseX, mouseY, +1 more.

vm_loadLoad project into the runtimeA

Load the open project into a headless Scratch VM (TurboWarp, JIT) for running and testing — no browser needed. Reflects the current in-memory edits; call again after editing to pick up changes. Returns a state snapshot.

Inputs: no named parameters.

vm_runRun the runtimeA

Advance the headless VM, then return a state snapshot. By default it runs in real time until every script finishes (so waits, timers and glides behave) or the budget elapses. Returns sprite positions, variables, lists, monitors, say/think bubbles, any pending question, running-thread count and errors. Also returns events: the ordered timeline of what happened since the previous vm_run (say/think, broadcasts, question/answer, errors), so you can assert on sequence, not just final state.

Inputs: paced, frames, seconds, untilIdle.

vm_stateRuntime stateA

A structured snapshot of the headless VM right now: every target with its position/size/direction/costume/visibility, variables and lists, visible monitors, say/think bubbles, the pending question, running-thread count and errors. Assert against these rather than a screenshot.

Inputs: no named parameters.

vm_stopStop the runtimeA

Stop every running script in the headless VM.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 43 tools

    Disambiguation4/5

    Tools are organized by clear resource categories — project I/O, sprite/target editing, block schemas, comments, assets, VM execution, and screenshots — so an agent can usually tell them apart. The main ambiguity is intentional duplication like screenshot vs screenshot_jpeg and the separate live vs headless run/stop tool pairs, though prefixes help a lot.

    Naming Consistency4/5

    The naming is overwhelmingly snake_case verb-first and predictable: open_, save_, list_, get_, set_, add_, remove_, delete_, and the vm_* family. Minor deviations like project_info, scratch_login, and vm_green_flag break the pattern slightly, and delete vs remove is used inconsistently across similar resources.

    Tool Count2/5

    43 tools is well above the 25+ threshold for a coherent MCP surface, and while each tool has a real purpose, the set feels heavy for agent selection. Several groups (the VM runtime tools, comment tools, asset tools, and screenshot variants) could plausibly be consolidated without losing much capability.

    Completeness4/5

    The surface covers the full editing lifecycle for sprites, scripts, variables, lists, comments, costumes, sounds, and project saving with both local and online workflows. Notable gaps include no way to create a brand-new project, list existing online projects, or remove broadcasts, but patch_target provides a low-level workaround for most of these.

    Related MCP Connectors

    Related MCP Servers