godot-mcp-shadows

# Godot MCP [](https://github.com/sponsors/Coding-Solo) [](https://modelcontextprotocol.io/introduction) [](https://godotengine.org) [](https://nodejs.org/en/download/) [](https://www.typescriptlang.org/) [](https://github.com/Coding-Solo/godot-mcp/commits/main) [](https://github.com/Coding-Solo/godot-mcp/stargazers) [](https://github.com/Coding-Solo/godot-mcp/network/members) [](https://opensource.org/licenses/MIT) ```text ((((((( ((((((( ((((((((((( ((((((((((( ((((((((((((( ((((((((((((( ((((((((((((((((((((((((((((((((( ((((((((((((((((((((((((((((((((( ((((( ((((((((((((((((((((((((((((((((((((((((( ((((( ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@((((((((((( (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@((((((((( ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@(((((((( ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@(((((((( (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@((((((((( ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@(((((((((((( ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@ ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ ((((((((( (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ (((((((((( (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@((((((((((( ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( ((((((((((((((((((((((((((((((((((((((((((((((((((((( ((((((((((((((((((((((((((((((((((((((((((((((( ((((((((((((((((((((((((((((((((( /$$ /$$ /$$$$$$ /$$$$$$$ | $$$ /$$$ /$$__ $$| $$__ $$ | $$$$ /$$$$| $$ \__/| $$ \ $$ | $$ $$/$$ $$| $$ | $$$$$$$/ | $$ $$$| $$| $$ | $$____/ | $$\ $ | $$| $$ $$| $$ | $$ \/ | $$| $$$$$$/| $$ |__/ |__/ \______/ |__/ ``` 一个用于与Godot游戏引擎交互的Model Context Protocol (MCP) server。 ## Introduction Godot MCP 使 AI 助手能够启动 Godot 编辑器、运行项目、捕获调试输出以及控制项目执行——所有这些都通过一个标准化的接口。 这种直接的反馈循环帮助像 Claude 这样的 AI 助手了解在真实的 Godot 项目中什么有效，什么无效，从而带来更好的代码生成和调试帮助。 ## Features - **Launch Godot Editor**：为特定项目打开 Godot 编辑器 - **Run Godot Projects**：在调试模式下执行 Godot 项目 - **Capture Debug Output**：检索控制台输出和错误消息 - **Control Execution**：以编程方式启动和停止 Godot 项目 - **Get Godot Version**：检索已安装的 Godot 版本 - **List Godot Projects**：在指定目录中查找 Godot 项目 - **Project Analysis**：获取有关项目结构的详细信息 - **Scene Management**： - 使用指定的根节点类型创建新场景 - 将节点添加到具有可自定义属性的现有场景 - 将精灵和纹理加载到 Sprite2D 节点中 - 将 3D 场景导出为用于 GridMap 的 MeshLibrary 资源 - 保存场景，并提供创建变体的选项 - **UID Management**（适用于 Godot 4.4+）： - 获取特定文件的 UID - 通过重新保存资源来更新 UID 引用 ## Requirements - 您的系统上安装了 [Godot Engine](https://godotengine.org/download) - Node.js 和 npm - 支持 MCP 的 AI 助手（Cline、Cursor 等） ## Installation and Configuration ### Step 1: Install and Build 首先，克隆存储库并构建 MCP server： ```bash git clone https://github.com/Coding-Solo/godot-mcp.git cd godot-mcp npm install npm run build ``` ### Step 2: Configure with Your AI Assistant #### Option A: Configure with Cline 添加到您的 Cline MCP 配置文件 (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`)： ```json { "mcpServers": { "godot": { "command": "node", "args": ["/absolute/path/to/godot-mcp/build/index.js"], "env": { "DEBUG": "true" // Optional: Enable detailed logging }, "disabled": false, "autoApprove": [ "launch_editor", "run_project", "get_debug_output", "stop_project", "get_godot_version", "list_projects", "get_project_info", "create_scene", "add_node", "load_sprite", "export_mesh_library", "save_scene", "get_uid", "update_project_uids" ] } } } ``` #### Option B: Configure with Cursor **Using the Cursor UI:** 1. 转到 **Cursor Settings** > **Features** > **MCP** 2. 单击 **+ Add New MCP Server** 按钮 3. 填写表格： - Name: `godot` (或者您喜欢的任何名称) - Type: `command` - Command: `node /absolute/path/to/godot-mcp/build/index.js` 4. 点击 "Add" 5. 您可能需要按 MCP server 卡右上角的刷新按钮来填充工具列表 **Using Project-Specific Configuration:** 在您的项目目录中的 `.cursor/mcp.json` 创建一个文件，内容如下： ```json { "mcpServers": { "godot": { "command": "node", "args": ["/absolute/path/to/godot-mcp/build/index.js"], "env": { "DEBUG": "true" // Enable detailed logging } } } } ``` ### Step 3: Optional Environment Variables 您可以使用以下环境变量自定义 server 行为： - `GODOT_PATH`：Godot 可执行文件的路径（覆盖自动检测） - `DEBUG`：设置为 "true" 以启用详细的 server 端调试日志记录 ## Example Prompts 配置完成后，您的 AI 助手会在需要时自动运行 MCP server。您可以使用如下提示： ```text "Launch the Godot editor for my project at /path/to/project" "Run my Godot project and show me any errors" "Get information about my Godot project structure" "Analyze my Godot project structure and suggest improvements" "Help me debug this error in my Godot project: [paste error]" "Write a GDScript for a character controller with double jump and wall sliding" "Create a new scene with a Player node in my Godot project" "Add a Sprite2D node to my player scene and load the character texture" "Export my 3D models as a MeshLibrary for use with GridMap" "Create a UI scene with buttons and labels for my game's main menu" "Get the UID for a specific script file in my Godot 4.4 project" "Update UID references in my Godot project after upgrading to 4.4" ``` ## Implementation Details ### Architecture Godot MCP server 使用捆绑的 GDScript 方法进行复杂操作： 1. **Direct Commands**：像启动编辑器或获取项目信息这样的简单操作直接使用 Godot 的内置 CLI 命令。 2. **Bundled Operations Script**：像创建场景或添加节点这样的复杂操作使用单个、全面的 GDScript 文件 (`godot_operations.gd`) 来处理所有操作。 这种架构提供了几个好处： - **No Temporary Files**：消除了对临时脚本文件的需求，保持您的系统清洁 - **Simplified Codebase**：将所有 Godot 操作集中在一个（有点）有组织的文件中 - **Better Maintainability**：可以更轻松地添加新操作或修改现有操作 - **Improved Error Handling**：在所有操作中提供一致的错误报告 - **Reduced Overhead**：最大限度地减少文件 I/O 操作，以获得更好的性能 捆绑的脚本接受操作类型和参数作为 JSON，允许灵活和动态的操作执行，而无需为每个操作生成临时文件。 ## Troubleshooting - **Godot Not Found**：将 GODOT_PATH 环境变量设置为您的 Godot 可执行文件 - **Connection Issues**：确保 server 正在运行并重新启动您的 AI 助手 - **Invalid Project Path**：确保路径指向包含 project.godot 文件的目录 - **Build Issues**：确保通过运行 `npm install` 安装了所有依赖项 - **For Cursor Specifically**： - 确保 MCP server 显示并且在 Cursor 设置中启用 (Settings > MCP) - MCP 工具只能使用 Agent 聊天配置文件运行 (Cursor Pro 或 Business 订阅) - 使用 "Yolo Mode" 自动运行 MCP 工具请求 ## License 此项目已获得 MIT 许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 [](https://mseep.ai/app/coding-solo-godot-mcp)