Godot-MCP 故障排查清单连接失败、命令报错、更改不生效的 8 种解决方案【免费下载链接】Godot-MCPAn MCP for Godot that lets you create and edit games in the Godot game engine with tools like Claude项目地址: https://gitcode.com/gh_mirrors/god/Godot-MCPGodot-MCP是一款让 Claude 通过 MCP模型上下文协议直接操作 Godot 游戏引擎的开源工具用自然语言就能创建节点、编辑 GDScript 脚本、保存场景。新手最容易卡住的就是连不上、报错了、改了没反应这三类问题。本文整理成一份完整的 Godot-MCP 故障排查清单8 个常见问题的解决方案一次讲清照着查就能快速定位。快速自检先判断卡在哪一环Godot-MCP 的通信链路是Claude Desktop → MCP ServerNode.js→ WebSocket → Godot 编辑器。哪一环断了症状不同现象大概率出问题的环节对应解决方案Claude 提示无法连接 GodotWebSocket / MCP Server 未启动方案 1、2、3终端报错、MCP 工具列表为空Node 服务没构建或没跑起来方案 4命令返回 error参数格式、节点路径写错方案 5、6命令成功但编辑器没变化场景未保存方案 7Claude 里根本看不到 Godot 工具Desktop 配置问题方案 8 完整链路原理可参考 docs/architecture.md排查思路就是沿这条链一节节查。方案 1检查 Godot 侧 WebSocket 服务是否已启动连接失败最常见的原因就是 Godot 里的服务压根没跑起来。在 Godot 编辑器右侧停靠栏打开Godot MCP Server面板由 addons/godot_mcp/ui/mcp_panel.gd 提供点击Start Server等状态指示器变为绿色才表示服务就绪面板下方的日志区会显示连接事件、命令执行与报错第一手排查信息就在这里。如果面板都没出现说明插件没启用进入 项目 → 项目设置 → 插件确认 Godot MCP 已勾选。安装步骤详见 docs/installation-guide.md。方案 2核对两端端口号是否一致默认 9080Godot 侧 WebSocket 默认监听9080端口见 addons/godot_mcp/websocket_server.gdMCP Server 侧默认连接ws://localhost:9080见 server/src/utils/godot_connection.ts。只要你在 Godot 面板里改过端口就必须同步修改 Node 侧配置可通过GODOT_WS_URL环境变量参考 docs/mcp-server-readme.md 的 Configuration 一节。两端不一致 必然连不上这是第二高频的故障。方案 3端口被占用或编辑器监听失败点 Start Server 却没反应按顺序检查端口被占用9080 已被其他程序占用会导致listen失败面板日志会打印错误逻辑在 addons/godot_mcp/mcp_server.gd。换一个空闲端口并按方案 2 同步到 Node 侧。macOS 网络权限Godot 编辑器可能被系统拦截了本地网络连接到 系统设置 → 隐私与安全 → 本地网络 中允许 Godot。防火墙拦截 localhost检查防火墙规则是否放行了 127.0.0.1 的本地回环通信。远程连接默认只接受 localhost 连接跨机器调试需在面板中开启 Allow Remote默认禁用。方案 4MCP Server 没有正确构建或启动如果 Godot 侧一切正常但终端里npm start报Cannot find module dist/index.js或一堆 TypeScript 错误多半是没构建确认 Node.js 版本≥ 18node -v查看在server目录下依次执行npm install和npm run build生成server/dist/index.js再执行npm start启动看到日志输出Connecting to Godot WebSocket server...后连接成功即会打印Connected。构建命令速查见 CLAUDE.md 的 Build Run Commands 一节。方案 5命令参数报错路径格式、节点类型、属性名命令返回status: error时先看 MCP 面板日志里的详细 message再核对三类高频错误路径格式Godot 资源路径必须以res://开头如res://scripts/player.gd节点路径形如/root/MainScene/UI/Label节点类型不存在node_type必须是引擎内置类型名如Node2D、Sprite2D、Label拼写错误会直接失败属性名写错update_node的property要与实际属性完全一致可先用get_node_properties查一遍再改。所有命令的参数定义都列在 docs/command-reference.md拿不准时直接对照查。方案 6命令超时与自动重连机制系统内置了超时保护与重试逻辑理解它们能避免假性故障单条命令默认20 秒超时timeout超时后 Promise 会 reject 并报错连接断开后最多自动重试 3 次每次间隔 2 秒maxRetries/retryDelay见 server/src/utils/godot_connection.ts。如果频繁看到超时错误复杂操作拆小一条消息只让 Claude 做一件事检查 Godot 编辑器是否卡死编辑器无响应时命令必然超时无返回长时间运行的批量任务建议分批执行别攒成大请求。方案 7更改不生效记住保存场景这最后一步这是新手最容易懵的问题Claude 明明回复成功了编辑器里却看不到新节点。核心原因——MCP 修改的是编辑器内存中的当前场景必须落盘才算数。让 Claude 执行save_scene保存场景或手动Ctrl S保存后刷新/重新打开场景若保存时也报错了比如文件被占用回到 MCP 面板日志找具体原因。官方文档中这一条的原话也在 docs/getting-started.md 的 Troubleshooting 一节Make sure the scene is saved after changes。养成每让 Claude 完成一组修改就保存一次的习惯问题基本绝迹。方案 8Claude Desktop 的 MCP 配置检查清单Claude 对话里根本看不到 Godot 工具时逐项核对 Desktop 配置示例见仓库根目录的 claude_desktop_config.jsonSettings → Developer 中已启用 Model Context Protocolcommand为nodeargs指向你本机的server/dist/index.js绝对路径示例文件里的路径是作者的机器路径务必改成自己的路径中含空格时注意引号改完配置后重启 Claude Desktop工具列表才会刷新。收尾8 项排查速查表#检查项关键动作1Godot WebSocket 服务面板 Start Server状态变绿2端口一致两端都是 9080或同步改3端口占用 / 权限换端口允许 Godot 本地网络权限4Node 服务构建npm install npm run build5命令参数res://路径、类型名、属性名6超时与重试拆分大任务检查编辑器响应7更改不生效保存场景后刷新编辑器8Desktop 配置路径改本机重启 Claude Desktop更多场景化的使用与排错示例可以继续看 docs/getting-started.mdGodot 插件的命令细节参考 docs/godot-addon-readme.md服务端细节参考 docs/mcp-server-readme.md。按这份清单从上往下过一遍90% 的 Godot-MCP 故障都能当场解决 【免费下载链接】Godot-MCPAn MCP for Godot that lets you create and edit games in the Godot game engine with tools like Claude项目地址: https://gitcode.com/gh_mirrors/god/Godot-MCP创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考