Scratch MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SCRATCH_MCP_OUT_DIR | No | Sets where save_project writes when no path is given; it defaults to ./scratch-projects under the working directory. | ./scratch-projects |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| create_projectA | Starts a fresh project in memory and sets its backdrop. Replaces any project currently open. Built-in backdrops: blank, solid, sky, hills, night, space, grid, room, underwater (use "solid:#223344" for a flat colour). |
| project_infoA | Lists sprites, costumes, sounds, scripts, variables and broadcasts in the open project. |
| save_projectA | Writes the project to a .sb3 file that opens in Scratch 3 (File > Load from your computer) or TurboWarp. |
| preview_projectA | Serves the project from localhost and returns a TurboWarp link that runs it immediately, without saving a file first. |
| add_backdropA | Adds a stage backdrop, either a built-in (blank, solid, sky, hills, night, space, grid, room, underwater) or an image file from disk. The newly added backdrop becomes the one shown. |
| add_spriteA | Adds a sprite using a built-in costume (ball, square, triangle, star, heart, arrow, dot, line, buddy), optionally tinted like "ball:red". To use character art from a file, use import_character instead. |
| import_characterA | Turns a jpg/png character picture into a sprite: cuts away the flat background so it sits properly on the backdrop, trims empty margins, scales it to fit the stage, and optionally builds talk frames — extra costumes that, alternated in a loop, make a still character look like it is talking. |
| add_costumeA | Adds another costume to an existing sprite, from a built-in shape or an image file. |
| add_soundB | Adds a sound to a sprite or the stage. Built-in sounds: pop, beep, boing, zap, click, chime, whoosh. Files must be .wav. |
| list_voicesA | Shows every offline text-to-speech voice available here, with its gender, locale and engine. Voice availability differs per machine, so check this before asking add_speech for a particular voice. |
| add_speechA | Synthesizes speech with the machine's offline text-to-speech engine and attaches it to a sprite as a Scratch sound — no network, no file needed. Returns the sound's duration and a ready-made mouth-loop repeat count, so the talking animation can be timed to the audio. Use {"play_sound": name} (not play_sound_until_done) before the mouth loop so the animation runs while the audio plays. |
| remove_spriteA | Deletes a sprite and everything on it. |
| add_scriptA | Compiles a JSON action list into real Scratch blocks and attaches it under a hat block. Example: {"target":"Cat","when":"flag","do":[{"say":["Hi!",2]},{"forever":[{"move":4},"bounce_on_edge"]}]}. Call dsl_reference for every available action, expression and hat. |
| clear_scriptsA | Deletes all blocks on a sprite or the stage, leaving costumes and sounds alone. |
| set_variableB | Declares a project-wide variable with a starting value. Variables are also created automatically the first time a script mentions them. |
| dsl_referenceA | Returns the full list of hat blocks, actions, expressions and built-in assets understood by add_script. Read this before writing scripts. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 16 tools
Each tool targets a distinct resource and action: sprites (add/import/remove), costumes, sounds, speech, backdrops, scripts, variables, and project-level operations. The only potential overlap (add_sprite vs import_character) is explicitly disambiguated in the descriptions, as is add_sound vs add_speech. No tool appears to duplicate another.
The majority of tools follow a consistent verb_noun pattern (add_*, list_*, create_*, save_*, preview_*, remove_*, clear_*, set_*, import_*). However, two tools (project_info, dsl_reference) use a noun-first naming convention, breaking the pattern slightly. This deviation is minor but noticeable.
With 16 tools, the server covers a broad but focused scope: project creation, sprite management, costumes, sounds, speech, backdrops, scripts, variables, and output (save/preview). Each tool serves a distinct purpose in the workflow, and the count is appropriate for the feature set offered.
The tool surface covers the full lifecycle of creating a Scratch project: create, populate (sprites, costumes, sounds, backdrops, scripts, variables), inspect, and export. Missing operations like editing individual costumes/sounds or renaming sprites are minor gaps that can be worked around (e.g., by removing and re-adding), and the included features are sufficient for most project-building tasks.