scratchattach-mcp

scratchattach-mcp

一个 MCP 服务，可让任意 Agent 连接到 Scratch。

Agent 可以访问 Scratch 平台并使用网站功能（例如社交功能），也可以实时编写 Scratch 项目代码。

---

目录

• 安装
• 配置
• 工具
  • 会话
  • 个人资料
  • 浏览 Scratch
  • 评论
  • 社交操作
  • 项目生命周期
  • 项目资源
  • 构建和发布
  • 参考
• 项目的制作过程
• 注意事项和易踩问题
• 测试

---

安装

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

如果你希望 Agent 能够编写项目代码，就需要使用 Rust 编写的 goboscript 工具链。通常只需让 Agent 阅读相关说明（通过 MCP 提供）并为你安装即可；如果你想手动安装：

$ 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

这些都是可选项，social_ 工具无需项目构建工具链也能运行。如果 Agent 想要创建项目，可以运行 project_check_toolchain 查看缺少哪些内容。

如果二进制文件不在 PATH 中，可以设置 GOBOSCRIPT_BIN / SB2GS_BIN。

配置

{
  "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
    }
  }
}

MCP 本身的所有配置数据都会持久保存在文件系统的 ~/.local/share/scratch-mcp/sessions.json 中。你可以使用 SCRATCH_MCP_DATA_DIR 或 SCRATCH_MCP_SESSION_FILE 环境变量覆盖此路径。只会存储会话 ID，不会存储密码，因此会话最终可能会过期。

---

工具

* 表示必填参数。

会话

工具	参数	说明
social_connect_session	path_to_env、scratch_username、scratch_password、scratch_session_id、browser_name、remember	通过 .env 文件、用户名和密码、会话 ID 或浏览器 Cookie 登录。默认在重启后保留会话。
social_list_sessions	—	列出已保存的会话及当前活动会话。
social_set_active_session	*username	选择后续工具要使用的账号。
social_verify_session	username	向 Scratch 查询已存储的会话是否仍有效。恢复的会话会在离线状态下重建，因此被撤销的会话在使用前看起来仍然正常。
social_forget_session	*username、logout	从内存和磁盘中删除会话；也可选择在 Scratch 上使其失效。

个人资料

工具	参数	说明
social_set_bio	*text	设置“关于我”。最多 200 个字符。
social_set_whatimworkingon	*text	设置“我正在做什么”。最多 255 个字符。
social_set_pfp	*file	使用 PNG/JPEG/GIF 设置头像。最大尺寸为 500×500。

浏览 Scratch

工具	参数	说明
social_get_user_info	*username、recent_comments	用户的个人资料，以及你是否关注了该用户和其最新个人资料评论的预览。
social_get_project_info	*id、recent_comments	项目的元数据，以及你是否为其点赞或收藏，还有评论预览。
social_search_projects	query、sort、limit、offset、language	搜索已分享的项目；未提供查询内容时，则浏览探索动态。可按 trending、popular 或 recent 排序。
social_check_inbox	limit、offset	活动消息、Scratch Team 通知以及待处理的 Scratcher 邀请。Scratch 会分别跟踪这些内容的未读状态，因此仅凭 unread_count 不能判断收件箱是否为空——请参阅 unread_elsewhere。

评论

这四种工具都接受 project、studio 或 profile 类型的 source。

工具	参数	描述
social_get_comments	*source、*source_id、limit、offset、page、include_replies	分页获取顶层评论。
social_get_comment_replies	*source、*source_id、*comment_id、limit、offset	获取一条顶层评论的回复。
social_post_comment	*source、*source_id、*content、parent_id、commentee_id	发布评论。最多 500 个字符。
social_reply_to_comment	*source、*source_id、*parent_id、*content、commentee_id	回复评论。parent_id 必须是顶层评论。

项目和工作室通过 limit + offset 分页，并单独获取回复。 个人资料通过 page 分页（每页 30 条，忽略 offset），并免费在 回复中内嵌返回。Scratch 只有一层嵌套：对回复的回复会存储在顶层评论下。

社交操作

工具	参数	描述
social_follow_user	*username、action	check（默认）、follow、unfollow、toggle。
social_like_project	*id、action	check（默认）、like、favourite、both、unlike、unfavourite、removeboth。点赞和收藏互相独立。
social_add_project_to_studio	*project_id、*studio_id	将项目添加到工作室。
social_become_scratcher	confirm	接受待处理的“成为 Scratcher”邀请。除非设置了 confirm，否则只报告资格，因为接受邀请即表示同意《社区准则》，且无法撤销。

这两种操作工具默认使用 check，因此不显式指定操作的调用不会意外更改任何内容。

项目生命周期

工具	参数	描述
project_new	*path、published_project_id、git	搭建一个新的 goboscript 项目并将其设为活动项目。
project_open	*path、published_project_id	注册现有项目目录。
project_download	*path、project_id、sb3_path、overwrite、verify	按 ID 或从本地 .sb3 反编译 Scratch 项目，生成可编辑的 .gs 源码。验证其仍可编译。
project_list	—	列出已知项目。
project_select	*path	选择活动项目。
project_info	path	精灵、发布目标和兼容性。
project_close	path	忘记一个项目。磁盘上的文件会保留。

按 ID 下载时会通过你的会话获取，因此未分享的项目也可以下载。

项目资源

工具	参数	描述
project_list_assets	*sprite、path	列出精灵声明的造型和声音。
project_add_costume	*sprite、file、svg、name、path	从文件或原始 SVG 标记添加造型。
project_add_sound	*sprite、*file、name、path	添加 MP3 或 WAV 文件。
project_remove_asset	*sprite、*kind、*name、path	移除造型或声音声明。

写入任何内容前都会检查格式和大小限制：Scratch 会静默拒绝加载包含不受支持音频格式的项目。

构建和发布

工具	参数	描述
project_build	path	编译为 .sb3。失败时会附带编译器诊断信息抛出错误。
project_summary	path	查看构建实际生成的内容：每个角色的积木和脚本数量、造型、声音、变量、图层顺序、素材大小，以及未使用素材、超大素材和过期构建的警告。
project_save_to_cloud	path、title、visibility、build、thumbnail	构建并上传，包括素材和缩略图。首次保存时创建项目，之后复用其 ID。visibility 可以是 public、private 或 unchanged。
project_set_thumbnail	file、path	设置已发布项目的缩略图。省略 file 时使用舞台背景。Scratch 只会在其编辑器中生成缩略图，因此否则上传的项目会显示灰色占位图。

参考

工具	参数	描述
project_editing_guide	—	创建或编辑项目之前请先阅读：Scratch 的硬性限制和 goboscript 入门指南。
project_goboscript_docs_help	page	goboscript 文档。不提供参数时会列出所有页面；传入路径可获取原始 Markdown。
project_check_toolchain	—	检查是否已安装 goboscript 和 sb2gs，以及它们是否可运行。

---

项目制作流程

以下是面向访问此 MCP 的 Agent 的说明。

1. 从 project_new 或 project_download 开始，以创建新项目，或下载现有项目并将其反编译。
2. 使用 project_check_toolchain 检查工具链是否可用，然后查看指南 project_editing_guide。如果遇到困难，可以通过 project_goboscript_docs_help 阅读语言文档。
3. 使用文件工具（Read/Edit/Write 等）编辑 .gs 文件。
   • 使用 project_add_costume / project_add_sound 添加素材。
   • 使用 project_build 构建，修复诊断信息后重复此步骤。
   • 使用 project_summary 确认构建内容符合预期。
   • 使用 project_save_to_cloud。

注意事项

• api.scratch.mit.edu 的缓存时间约为 15 秒，因此写入后立即读取可能会返回旧值。
• Scratch 的搜索经常不可用，可能会从其搜索集群返回 429，或从其缓存层返回 503。social_search_projects 会重试，并明确说明问题出在 Scratch。
• project_* 工具中的相对路径会在项目目录内解析，而不是在服务的工作目录中解析。
• 反编译属于语义修复，并非逐字节复制。真实项目中包含 goboscript 无法表达的内容，例如同一角色中的重名变量、映射到同一名称的两个自定义积木，以及引用已删除素材的积木。这些内容会被重命名或丢弃，并会报告每项更改。我们会尝试使用 SB3 规范化器修复这些问题，但请注意，并非所有情况都能完美处理。

测试

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

这些测试不使用网络或凭据，只是离线测试。因此它们可能在某些方面“不完整”，但我们只能尽力而为；）。

致谢

• 我 // uukelele
• goboscript、sb2gs（aspizu）
• scratchattach（TimMcCool、faretek1、TheCommCraft）