scratch-mcp

An MCP server for the Scratch programming platform. Lets an AI assistant browse users, projects and studios through Scratch's public API, read a shared project's actual blocks/sprites, and (optionally) act on your own Scratch account.

Requirements

• Node.js 18+

Install

npm install
npm run build

Configuration

Public browsing tools need no configuration. The account-action tools (comments, love, favorite, follow, messages) require a Scratch login, set via environment variables:

Variable	Description
SCRATCH_USERNAME	Your Scratch username
SCRATCH_PASSWORD	Your Scratch password

The server logs in lazily (on first authenticated tool call) by replicating the browser login flow (CSRF token → /login/ → session cookie → session token), the same way the scratch.mit.edu website itself does. No token is stored on disk; it lives only in the running process's memory.

Usage with an MCP client

{
  "mcpServers": {
    "scratch": {
      "command": "node",
      "args": ["C:/path/to/scratch-mcp/dist/index.js"],
      "env": {
        "SCRATCH_USERNAME": "your-username",
        "SCRATCH_PASSWORD": "your-password"
      }
    }
  }
}

Omit the env block entirely if you only want the public/read-only tools.

Tools

Users

• scratch_get_user, scratch_get_user_projects, scratch_get_user_favorites, scratch_get_user_followers, scratch_get_user_following, scratch_get_user_comments

Projects

• scratch_get_project — public metadata
• scratch_get_project_json — the project's actual sb3 content (sprites, scripts/blocks, extensions)
• scratch_get_project_remixes, scratch_get_project_studios
• scratch_get_project_comments, scratch_get_project_comment_replies

Studios

• scratch_get_studio, scratch_get_studio_projects, scratch_get_studio_comments, scratch_get_studio_curators, scratch_get_studio_managers, scratch_get_studio_activity

Discovery

• scratch_search_projects, scratch_explore_projects, scratch_get_news

Escape hatch

• scratch_raw_request — call any GET endpoint on api.scratch.mit.edu directly

Account actions (require SCRATCH_USERNAME/SCRATCH_PASSWORD)

• scratch_get_session_status, scratch_get_my_messages, scratch_get_my_message_count
• scratch_post_comment — post one comment on a project, studio, or profile
• scratch_set_project_love, scratch_set_project_favorite — love/favorite a single project
• scratch_set_user_follow — follow/unfollow a single user

A note on responsible use

Scratch is primarily a learning platform for kids. The account-action tools above each act on one project/user/comment per call by design — there's no bulk "follow this list of users" or "comment on N projects" tool. Please don't use them to automate mass engagement (spam commenting, follow-for-follow botting, love/favorite farming); that violates Scratch's Community Guidelines and Terms of Use, and can get the account banned.

The login flow and the comment/love/favorite/follow endpoints are undocumented (there's no official write API), reverse-engineered from the website's own network calls. They may break if Scratch changes its site internals.

Development

npm run build   # compile TypeScript to dist/
npm start       # run the compiled server over stdio

License

MIT