Cocos MCP 接続トラブル：Cursor に cocos-creator が出ないとき

Cocos MCP を Cursor（や他の MCP クライアント）に繋ぐとき、つまずきの大半は「プロンプトが下手」ではなく、橋がそもそも未接続なこと——エディタ側サービスが止まっている、または AI IDE に cocos-creator が出ない。

「Cursor が壊れた / 繋がらない」という言い方なら、まず Cursor 側の症状から：CursorがCocos Creator MCP接続後に壊れた？。

MCPでできることや「Cocos Creator AI」との違いがまだ曖昧なら、先にCocos Creator MCPとはを読んでください。

本記事は 症状 → 原因 → 対処 で、Creator 2.x と 3.x をカバーする。導入の全体手順は：

• Cocos Creator 3.x MCP インストール
• Cocos Creator 2.x MCP インストール

例は Cursor。Claude Code、Codex なども MCP リロードと設定確認は同様。

まず：どの層で止まっているか

MCP 経路は四層。どれが壊れても「繋がらない」に見える。

1. プラグイン導入済み・有効
        ↓
2. パネルでアクティベート済み（アカウント／コード）
        ↓
3. MCP Server が「実行中」（localhost）
        ↓
4. AI IDE に設定が入り、MCP 一覧が接続表示

見える症状	先に見る層
「拡張 → Cocos MCP Server / MCP Server」が無い	1：パッケージ版、導入パス、再起動
パネルは開くが起動できない／未アクティベート	2：アカウントとコード
「サービス起動」しても「実行中」にならない	3：ポート、ファイアウォール、アクティベート
Creator は「実行中」なのに Cursor に cocos-creator が無い	4：クイック設定、MCP リロード、設定ファイル
Cursor は接続表示だがシーンノードが列挙できない	検証プロンプト、ツール勾選、正しいプロジェクト

症状 A：メニューに MCP 拡張が無い

想定原因

1. 2.x / 3.x パッケージの混用
2. 3.x：拡張管理で未インポート、または無効のまま
3. 2.x：packages/<プラグイン名>/ に無い、または解凍の一段ネスト過多
4. 2.x：packages 配置後に Creator を完全再起動していない

対処

Creator 3.x の場合：

1. ダウンロードは Cocos MCP 3.x（2.x ではない）
2. プロジェクトを開く → 拡張 → 拡張管理 → 拡張をインポート → 3.x 圧縮包
3. 一覧で cocos-mcp-server が有効であることを確認
4. メニューが無いなら Creator を終了し、同じプロジェクトを開き直す

Creator 2.x の場合：

1. ダウンロードは Cocos MCP 2.x
2. 解凍後の想定構造：

プロジェクトルート/
  packages/
    <プラグイン名>/          ← ここに直接置く
      package.json           ← このパスに存在する（名前は実パッケージに従う）

3. 誤ったネスト例：

packages/
  xxx-mcp-unzip/
    <プラグイン名>/
      package.json

4. パス修正後、シーン更新ではなく Creator を終了して再起動し、拡張 → MCP Server を確認。

症状 B：パネルは開くがアクティベート／起動できない

想定原因

• 対応する Pro 権限がアカウントに無い
• アクティベーションコード期限切れ、メール不一致
• 未アクティベートのまま「サービス起動」

対処

1. MCP パネルを開く（3.x：拡張 → Cocos MCP Server → Open Mcp Panel；2.x：拡張 → MCP Server）
2. 次のいずれかでアクティベート：
   • VberAI アカウント + パスワード
   • メール + アクティベーションコード
3. 公式アカウントセンターでプラン／コードを確認してから再試行
4. 成功後に MCP Server 設定で「サービス起動」

未アクティベートでは多くの場合「実行中」にならない。Cursor の前にエディタ側を直す。

症状 C：「サービス起動」しても「実行中」にならない

想定原因

1. まだ未アクティベート（症状 B）
2. ポート占有（3.x は多くの場合デフォルト 3000；2.x はパネル表示に従う）
3. ファイアウォール等が localhost 待受を遮断

対処

1. MCP Server 設定でポートを確認（以下は 3000 例——パネルの値に置き換え）
2. 端末で待受確認：

macOS / Linux：

lsof -iTCP:3000 -sTCP:LISTEN

Windows（PowerShell）：

netstat -ano | findstr :3000

3. 他プロセスが占有している場合：
   • そのプロセスを終了する、または
   • パネルで空きポートに変更してから再起動
4. 127.0.0.1 を遮断しない（MCP を公網に出さない）
5. パネルが 実行中 になってから Cursor 側を設定

症状 D：Creator は実行中なのに Cursor に cocos-creator が無い

「接続失敗」で最も多い型：エディタは正常、クライアントに設定が載っていない。

対処（順に）

1. Creator で MCP パネルがまだ 実行中 か確認（ポート変更や再起動で止まることがある）
2. ツール管理で必要なツールにチェック
3. クイック設定 → Cursor → 自動設定 で「設定済み」になるまで
4. Cursor の MCP／ツール一覧：
   • cocos-creator（またはパネル表記名）があること
   • 無ければ MCP をリロード（または Cursor 再起動）
5. それでも無い：Cursor の MCP 設定にローカル橋（127.0.0.1 + パネルポート）が入っているか確認

自動設定の形は Cursor 版で異なる。手動確認の観点：

• サービス名が Cocos MCP（例：cocos-creator）
• ホストが 127.0.0.1 / localhost、ポートが Creator と一致
• LAN／公網 IP の誤記がない

設定変更後は 必ず MCP を再リロード。しないと UI が古い状態のまま。

他の AI IDE

クイック設定で Claude Code、Codex、Windsurf、Cline 等を選び、「自動設定 → そのクライアントで MCP リロード」。Cursor 済み＝全 IDE 接続済みではない。

症状 E：接続表示なのにシーン列挙／ノード変更ができない

想定原因

1. Creator で開いているプロジェクト／シーンと質問が不一致
2. ツール管理で必要能力がオフ
3. 「ディスク上のスクリプト」だけ見て、エディタ文脈を検証していない

検証

Cursor で読み取り専用プロンプト：

現在 Cocos Creator で開いているシーンのルートノード名を列挙してください。

結果	意味
Hierarchy と一致	橋 OK。小さな書き込みテストへ
明確なエラー／ツール無し	症状 C/D へ戻る
架空のノード名	MCP 未使用の可能性。接続と勾選を確認

続けて小さな書き込み（一時ノード作成→削除）。大きな変更の前にコミット。

2.x / 3.x 早見表

項目	Creator 3.x	Creator 2.x
製品ページ	cocos（3.x）	cocos2x
導入	拡張管理 → インポート	プロジェクト packages/ へ解凍
導入後	一覧で有効化	必ず再起動
パッケージ	3.x のみ	2.x のみ
詳細	3.x インストール	2.x インストール

混用は「メニュー無し」「インポート失敗」になりやすい。先に本表。

推奨順（5 分チェックリスト）

上から順に。多くは前四つで止まる。

1. Creator メジャー版と MCP 圧縮包が一致（2.x↔2.x、3.x↔3.x）
2. 拡張有効／packages パス正しい、2.x は再起動済み
3. パネルでアクティベート成功
4. パネルが 実行中；ポート衝突なし
5. 現在の IDE で「クイック設定 → 自動設定」済み
6. AI IDE で MCP リロードし cocos-creator 表示
7. 読み取りプロンプトで現在開いているシーンのルートが列挙できる

それでもダメなときに残す情報

サポートや同僚へ渡す内容：

• Creator 正確な版（例：3.8.x / 2.4.x）
• MCP パッケージ種別（2.x または 3.x Pro）
• パネルが「実行中」か、ポート番号
• AI IDE 名・版、MCP 一覧のスクショ
• 読み取り検証プロンプト原文と返答

橋は localhost のみ。MCP ポートを公網に出さない。

関連ドキュメント

• Cocos Creator 3.x MCP インストール
• Cocos Creator 2.x MCP インストール
• Cocos Creator MCP 動画セットアップ
• エンジン選定：Godot MCP vs Unity MCP vs Cocos MCP