scratchattach-mcp

An MCP server that allows any agent to connect to Scratch.

The agent can access the Scratch platform to interact with site features (e.g. social features), or code Scratch projects live.

Contents

• Install
• Configuration
• Tools
  • Sessions
  • Profile
  • Reading Scratch
  • Comments
  • Social actions
  • Project lifecycle
  • Project assets
  • Building and publishing
  • Reference
• How a project gets made
• Notes and gotchas
• Tests

Install

$ gh repo clone uukelele/scratch-mcp
$ cd scratch-mcp
$ uv sync

If you want your agent to be able to code projects, you will need the `goboscript` toolchain, in Rust. Usually you can simply get the agent to read the instructions (exposed via MCP) and install it for you; but if you wish to do it manually:

$ rustup toolchain install nightly
$ cargo +nightly install --git https://github.com/aspizu/goboscript    # compiler
$ cargo install --git https://github.com/aspizu/sb2gs sb2gs-cli        # decompiler

These are optional, `social_` tools work without the project building toolchain. The agent can run `project_check_toolchain` to see what's missing if it wishes to create any projects.

If the binaries are not on PATH, you can set `GOBOSCRIPT_BIN` / `SB2GS_BIN`.

Configuration

{
  "mcpServers": {
    "scratch": {
      "command": "/home/x/scratch-mcp/.venv/bin/python",
      "args": ["-m", "scratch_mcp"],
      "cwd": "/home/x/scratch-mcp",
      "env": { "PYTHONPATH": "/home/x/scratch-mcp" },
      "timeout": 600000 // compiling / decompiling / publishing can take quite some time
    }
  }
}

All configuration data for the MCP itself persist on the filesystem at `~/.local/share/scratch-mcp/sessions.json`. You can override this path with `SCRATCH_MCP_DATA_DIR` or `SCRATCH_MCP_SESSION_FILE` environment variables. Only the session ID is stored, not the password, which means sessions can expire eventually.

Tools

`*` marks a required argument.

Sessions

Profile

Reading Scratch

Comments

All four accept `source` of `project`, `studio` or `profile`.

> Projects and studios page by `limit` + `offset` and fetch replies separately.

> Profiles page by `page` (30 per page, `offset` ignored) and return replies

> inline for free. Scratch has only one level of nesting: a reply to a reply is

> stored against the top-level comment.

Social actions

Both action tools default to `check`, so a call without an explicit action

cannot change anything by accident.

Project lifecycle

Downloading by id fetches through your session, so unshared projects work.

Project assets

Format and size limits are checked before anything is written: Scratch silently

refuses to load a project containing an unsupported audio format.

Building and publishing

Reference

How a project gets made

These are instructions for agents accessing the MCP.

1. Start with `project_new` or `project_download` to either create a new project, or to download an existing project and decompile it.

2. Check your toolchain availability with `project_check_toolchain` and then view the guide with `project_editing_guide`. You can read the language docs, if you get stuck, with `project_goboscript_docs_help`.

3. Edit the `.gs` files with your file tools (Read/Edit/Write/etc.).

Notes and gotchas

• `api.scratch.mit.edu` caches for roughly 15 seconds, so a read straight after a write can report the old value.
• Scratch's search is frequently unavailable, answering 429 from its search cluster or 503 from its cache layer. `social_search_projects` retries and says plainly when the fault is Scratch's.
• Relative paths in `project_*` tools resolve inside the project directory, not the server's working directory.
• Decompiling is a semantic repair, not a byte-perfect copy. Real projects contain things goboscript cannot express — duplicate variable names in one sprite, two custom blocks that map to the same name, blocks referencing deleted assets. These are renamed or dropped, and every change is reported. We try to fix this using our SB3 normalizer, but please note that not everything is perfect.

Tests

$ .venv/bin/python tests/test_offline.py

No network and no credentials, these tests are just offline tests. So they might be "incomplete" as a way but really we just hope for the best ;).

Credits

• me // uukelele
• goboscript, sb2gs (aspizu)
• scratchattach (TimMcCool, faretek1, TheCommCraft)