scratchattach-mcp

scratchattach-mcp

あらゆるエージェントがScratchに接続できるMCP サーバーです。

エージェントはScratchプラットフォームにアクセスして、サイトの機能（ソーシャル機能など）を利用したり、Scratchプロジェクトをその場でコーディングしたりできます。

---

目次

• インストール
• 設定
• ツール
  • セッション
  • プロフィール
  • Scratchの閲覧
  • コメント
  • ソーシャルアクション
  • プロジェクトのライフサイクル
  • プロジェクトのアセット
  • ビルドと公開
  • リファレンス
• プロジェクトの作成方法
• 注意点と落とし穴
• テスト

---

インストール

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

エージェントがプロジェクトをコーディングできるようにするには、Rust製のgoboscriptツールチェーンが必要です。通常は、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_ツールはプロジェクトのビルド用ツールチェーンがなくても動作します。プロジェクトを作成する場合、エージェントは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	「About me」を設定します。最大200文字です。
social_set_whatimworkingon	*text	「What I'm working on」を設定します。最大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が0でも受信箱が空とは限りません。unread_elsewhereを参照してください。

コメント

4 つすべてで、source に project、studio、または profile を指定できます。

ツール	引数	説明
social_get_comments	*source, *source_id, limit, offset, page, include_replies	最上位のコメントをページ単位で取得します。
social_get_comment_replies	*source, *source_id, *comment_id, limit, offset	1 つの最上位コメントへの返信を取得します。
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 でページ分けし（1 ページあたり 30 件、offset は無視されます）、返信も インラインで無料で返されます。Scratch のネストは 1 階層のみです。返信への返信は 最上位のコメントに紐付けて保存されます。

ソーシャルアクション

ツール	引数	説明
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	保留中の「スクラッチャーになる」招待を承諾します。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 にアクセスするエージェント向けの手順です。

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 では表現できないもの（1 つのスプライト内で重複する変数名、同じ名前に対応付けられる 2 つのカスタムブロック、削除済みアセットを参照するブロックなど）が含まれています。これらは名前が変更されるか削除され、変更内容はすべて報告されます。SB3 ノーマライザーを使って修正を試みていますが、完全ではない点にご注意ください。

テスト

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

ネットワークも認証情報も使わない、オフラインテストのみです。そのため、不十分な部分もあるかもしれませんが、うまくいくことを願っています ;）。

クレジット

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