scratch-mcp
Enables editing Scratch .sb3 projects, including sprites, scripts, costumes, sounds, variables, lists, and broadcasts, as well as opening, saving, and sharing projects on scratch.mit.edu and running them in a headless VM.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scratch-mcp Open my Scratch project and make the cat say 'hi' for 2 seconds when clicked."
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.
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 stdioRelated 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 stdioConfigure 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>.mcpbThen 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.sb3into 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, thenproject.json).share_project { projectId?, confirm? }— publish a project so it's public.
push_to_scratchandshare_projectchange the live project, so they always ask you to confirm first — via an MCP elicitation prompt when your client supports it, otherwise by requiringconfirm: 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 rawproject.jsonentry (blocks, costumes, sounds, …), or a subtree at a JSON Pointer. Read this before authoring apatch_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 installedscratch-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 dropdownoptions, and a ready-to-adapt example block JSON. Dynamic menu options (sprites, sounds, costumes, broadcasts, …) are filled from the open project; passtargetto enumerate that sprite's own costumes and sounds. Covers built-in extension blocks too (pen_*,music_*,microbit_*, …), generated from each extension'sgetInfo().
Extensions
enable_extension { id, url? }— register an extension so its blocks load and show in the palette (required before using any<id>_…block). Pass justidfor a built-in (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor); addurlfor a custom/third-party (TurboWarp) extension.list_blocks { category: "<id>" }andget_block_schemadescribe built-in extension blocks;patch_targetwarns when a block uses an extension that isn't enabled. Custom extensions are opaque — mirror an existing block viaget_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 intoget_target_json; the patch applies atomically (all-or-nothing) and the result reports advisorywarningsfor unknown opcodes or inputs. Patchingcostumes/soundsarrays doesn't move asset bytes — useadd_costume/remove_costumefor 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 aneventstimeline (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 answerask and wait.vm_stop— stop all scripts.
Live reload & screenshots (require the bridge + userscript)
reload { path? }— load an.sb3from 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;quality1–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 previousvm_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 vialogging/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 thevm_runchannel 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 toolsadd_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).
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
Scored across 43 tools
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.
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.
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.
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
Build and inspect browser-based 3D games: projects, scenes, Lua scripts, assets and publishing.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Build and change Discord bots by describing them: slash commands, events, embeds, modals and data.
Build 3D web apps: physics, audio, music, Blender import. Live edits, undo, versions, publishing.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to programmatically edit Scratch .sb3 projects and preview changes live in TurboWarp Desktop via MCP tools and a live-reload bridge.2Mozilla Public 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, compile, and run Scratch projects by editing plain text and using a live editor loop.30 npm1Mozilla Public 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to programmatically edit CapCut Desktop and JianYing Pro projects by directly manipulating native draft files, supporting multi-track timelines, keyframing, transitions, subtitles, and headless previews.245MIT
- AlicenseAqualityBmaintenanceEnables AI clients to create, edit, run, and inspect ScratchJr Desktop projects using natural language, including characters, backgrounds, text, sounds, and programming blocks.17MIT