Minimal Godot MCP

🚀 minimal-godot-mcp

輕量級MCP服務器，將Godot LSP與MCP客戶端連接起來，用於GDScript驗證

本項目旨在以最小的開銷提供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中的上下文使用示例：

📦 安裝指南

目前該軟件包尚未發佈到npm，你需要克隆項目並在本地進行構建：

git clone https://github.com/ryanmazzolini/minimal-godot-mcp.git
cd minimal-godot-mcp
npm install
npm run build

💻 使用示例

基礎用法

當你編輯一個有語法錯誤的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"
      }
    ]
  }
}

高級用法

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": [...]
  }
}

📚 詳細文檔

配置

環境變量

在MCP客戶端配置中設置以下環境變量，以自定義行為：

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

比較

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項目中是否有效
• 保持功能範圍專注於診斷（不涉及項目操作）

故障排除

“端口6007連接被拒絕”

• Godot編輯器未運行
• 項目設置中LSP未啟用
• 防火牆阻止了本地連接

“未返回診斷信息”

• 文件不屬於Godot項目
• 文件未在編輯器中打開（LSP需要上下文）
• 語法實際上是有效的

“診斷信息過時”

• 文件更改時緩存未失效
• LSP未發送更新通知

啟用LSP調試日誌

在Godot中：項目 → 項目設置 → 網絡 → 語言服務器 → 日誌

相關項目

• 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獲取詳細信息。