Godot MCP Server

godot-mcp 让 MCP 客户端能够检查、验证、测试、导出和查询 Godot 项目。它支持无头 Godot 命令，并可选择从打开的 Godot 编辑器中获取实时状态。

环境要求

• Node.js 18 或更高版本

• 本地安装 Godot 4.1 或更高版本

• 包含 project.godot 的 Godot 项目

实时编辑器工具还需要下文所述的 MCP Bridge 插件。其余工具以无头模式运行。

Related MCP server: godot-ai-mcp

安装

从本地检出安装

npm install
npm run build

从 npm 安装（发布后）

npx -y @zbrkic/godot-mcp --project /path/to/godot-project --godot /path/to/godot

配置 MCP 客户端

始终提供项目路径。MCP 桌面客户端通常在其自己的工作目录中启动服务器，因此仅靠自动项目发现并不可靠。

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@zbrkic/godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "C:/Source/my-game",
        "GODOT_PATH": "C:/Program Files/Godot/Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

等效的命令行选项为：

godot-mcp --project /path/to/godot-project --godot /path/to/godot

仅当 godot 可执行文件已在 PATH 中时，GODOT_PATH/--godot 才是可选的。在 Windows 上，优先使用 _console.exe 可执行文件。

启用实时编辑器工具

1. 将 godot-plugin/addons/mcp_bridge 复制到 <your-project>/addons/mcp_bridge。

2. 在 Godot 中，打开 项目 > 项目设置 > 插件 并启用 MCP Bridge。

3. 使用实时工具时保持 Godot 编辑器处于打开状态。

该桥接默认监听 127.0.0.1:7000。在 project.godot 中设置 mcp/plugin/port 可覆盖该端口；服务器会从上述配置的项目中读取该设置。请在生产导出预设中排除 addons/mcp_bridge/*。

工具

• 项目与导出：get_project_settings、list_export_presets、export_project

• 测试与验证：run_tests、validate_scene、validate_script、run_scene、format_gdscript

• 场景与资源：inspect_scene_tree、find_nodes、get_node_properties、get_node_connections、list_resources、get_resource_dependencies、resolve_path、get_resource_info

• 文档：verify_api、get_help

• 实时编辑器：get_editor_selection、get_open_scenes

大多数工具返回结构化的 JSON 结果，包含 success、data、errors、warnings 以及计时元数据。

开发与验证

npm test              # TypeScript build plus MCP handshake and parser tests
npm run test:godot    # GDScript syntax checks; requires GODOT_PATH or godot on PATH
npm pack --dry-run    # Inspect the files that would be published

GitHub Actions 会在推送和拉取请求时运行 Node/MCP 测试和 Godot 插件检查。

发布清单

1. 更新 package.json 中的版本号。

2. 运行 npm test、npm run test:godot 和 npm pack --dry-run。

3. 使用 npm publish 发布，并创建对应的 GitHub 发布。

许可证

本项目采用 MIT 许可证 授权。