Minimal Godot MCP

🚀 minimal-godot-mcp

Godot LSPをMCPクライアントに接続し、GDScriptの検証を軽量に行うMCPサーバーです。

このプロジェクトは、最小限のオーバーヘッドでGodotの診断情報を提供することを目的として構築されています。Claude、Cursor、その他のMCPクライアントで即座にGDScriptの構文フィードバックを得ることができ、Godotに切り替えたり、カスタムプラグインを使用する必要はありません。GodotのネイティブLSPへの軽量なブリッジです。

🚀 クイックスタート

前提条件

• Node.js 24以上
• LSPが有効になったGodot 3.2以上または4.x

セットアップ

⚠️ 重要提示

このパッケージはまだnpmに公開されていません。現時点では、ローカルでクローンしてビルドしてください。

# クローンとビルド
git clone https://github.com/ryanmazzolini/minimal-godot-mcp.git
cd minimal-godot-mcp
npm install
npm run build

# プロジェクトを開いてGodotエディタを起動

MCPクライアント（例：Claude Code）をローカルビルドを使用するように設定します。

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/minimal-godot-mcp/dist/index.js"]
    }
  }
}

💡 使用建议

環境変数とクライアント固有の例については、設定を参照してください。

MCPクライアントを再起動して、.gdファイルの編集を開始しましょう✨

✨ 主な機能

• 🔌 ゼロコンフィグLSP統合 - Godotのネイティブ言語サーバーを使用します（プラグインや追加の依存関係は不要）
• ⚡ 高速診断 - 単一ファイルのチェックは1秒未満で返されます
• 📦 最小限のフットプリント - メモリ使用量は10MB未満、コア実装は200行未満
• 💬 低コンテキストオーバーヘッド - AIトークンの使用を最小限に抑えるための軽量なレスポンス
• 🔄 強力な接続 - Godotの再起動と再接続を自動的に処理します
• 🤝 互換性良好 - godot-vscode-pluginや他のLSPクライアントと互換性があります
• 🌐 ワークスペーススキャン - すべての.gdファイルの一括チェックがオプションで利用可能

Claude Codeでのコンテキスト使用例を見てみましょう。

📦 インストール

環境変数

MCPクライアントの設定でこれらの環境変数を設定することで、動作をカスタマイズできます。

• GODOT_LSP_PORT: デフォルトのポート選択を上書きします。 デフォルト: ポート6007、6005、6008を順に試します。 例: "GODOT_LSP_PORT": "6005"
• GODOT_WORKSPACE_PATH: LSPの初期化に使用するGodotプロジェクトのパスを設定します。 デフォルト: Godotの通知からワークスペースを使用します。 例: "GODOT_WORKSPACE_PATH": "/absolute/path/to/your/godot/project"

MCPクライアントの例

Claude Code (~/.claude/config.json)

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/minimal-godot-mcp/dist/index.js"],
      "env": {
        "GODOT_LSP_PORT": "6007",
        "GODOT_WORKSPACE_PATH": "/absolute/path/to/your/godot/project"
      }
    }
  }
}

💻 使用例

基本的な使用法

1. プロジェクトを開いてGodotエディタを起動します。
2. LSPが実行されていることを確認します: nc -zv localhost 6007
3. MCPクライアントを有効にしてGDScriptファイルを編集します。
4. 即座に構文エラーのフィードバックを受け取ります。

MCPツール

get_diagnostics

高速な単一ファイルの診断チェック（1秒未満）

入力

{
  "file_path": "/absolute/path/to/script.gd"
}

出力

{
  "diagnostics": {
    "/path/to/file1.gd": [
      {
        "line": 42,
        "column": 10,
        "severity": "error",
        "message": "Expected identifier after '.'",
        "code": "GD0001"
      }
    ]
  }
}

scan_workspace_diagnostics

⚠️ 高コストの操作 - ワークスペース内のすべての.gdファイルをスキャンします（100ファイル以上の場合、5 - 30秒かかります）。ワークスペース全体のエラーチェックには控えめに使用してください。GODOT_WORKSPACE_PATH環境変数が必要です。

入力

{}

出力

{
  "files_scanned": 150,
  "files_with_issues": 3,
  "scan_time_seconds": 12.45,
  "diagnostics": {
    "/path/to/file1.gd": [...],
    "/path/to/file2.gd": [...]
  }
}

実際の例 構文エラーのあるGDScriptファイルを編集するとき

# player.gd
extends CharacterBody2D

func _ready():
    velocity. = Vector2(100, 0)  # Missing identifier after '.'

MCPクライアントは次のようなデータを受け取ります。

{
  "diagnostics": {
    "/path/to/player.gd": [
      {
        "line": 5,
        "column": 14,
        "severity": "error",
        "message": "Expected identifier after '.'",
        "code": "parse-error"
      }
    ]
  }
}

📚 詳細文档

比較

minimal-godot-mcpが他のGodot MCPサーバーとどのように異なるかを見てみましょう。

minimal-godot-mcpを使用する場合: AI支援によるGDScript編集時に軽量な構文チェックが必要な場合 他のサーバーを使用する場合: シーン管理、ノード作成、または完全なプロジェクト制御が必要な場合

開発

アーキテクチャ

┌─────────────┐         ┌────────────────────┐         ┌────────────┐
│ MCP Client  │ ◄─MCP─► │ minimal-godot-mcp  │ ◄─LSP─► │   Godot    │
│             │         │   (TypeScript)     │         │   Editor   │
└─────────────┘         └────────────────────┘         └────────────┘

LSP通信

1. TCPを介してGodot LSPに接続します（localhostのポート6007、6005、6008を試します）
2. LSPのinitializeリクエストを送信します
3. textDocument/didOpenでドキュメントを同期します
4. textDocument/publishDiagnostics通知を受け取ります
5. MCPのget_diagnosticsツールを介してキャッシュし、提供します

テスト

npm test          # 単体テスト
npm run lint      # ESLint + Prettier

手動テスト

1. テストプロジェクトでGodotを起動します
2. npm run devを実行します
3. MCPクライアントを設定します
4. .gdファイルに構文エラーを導入します
5. 診断情報が表示されることを確認します

コントリビューション

コントリビューションを歓迎します！セットアップについては開発を参照してください。提出する前に

• npm run formatとnpm testを実行してください
• 実際のGodotプロジェクトで変更が機能することを確認してください
• 診断に焦点を当てた範囲を維持してください（プロジェクト操作は不要）

トラブルシューティング

"Connection refused on port 6007"

• Godotエディタが実行されていない
• プロジェクト設定でLSPが無効になっている
• ファイアウォールがlocalhostをブロックしている

"No diagnostics returned"

• ファイルがGodotプロジェクトの一部ではない
• ファイルがエディタで開かれていない（LSPにコンテキストが必要）
• 構文が実際には有効である

"Stale diagnostics"

• ファイル変更時にキャッシュが無効になっていない
• LSPが更新通知を送信していない

LSPデバッグログを有効にする

Godotで: Project → Project Settings → Network → Language Server → Log

関連プロジェクト

• Model Context Protocol - プロトコル仕様
• Godot LSP Documentation - Godotの言語サーバーの設定
• awesome-mcp-servers - MCPサーバーの選りすぐりのリスト
• godot-vscode-plugin - 公式のVSCode拡張機能（同じLSPを使用）

代替のGodot MCPサーバー

• ee0pdt/Godot-MCP - カスタムプラグインを介した完全なプロジェクト制御
• Coding-Solo/godot-mcp - CLIベースのGDScript操作

📄 ライセンス

MITライセンス - LICENSEを参照してください