Godot MCP Lite

本地加固版 Godot MCP，fork 自 KeeVeeG/godot-mcp 并做安全与生命周期加固，替换 agents/cursor/mcp.json 中旧的 godot-keeveeg 条目（现名为 godot）。

解决的问题

Related MCP server: AI-godot-mcp

架构

Cursor / MCP client
   │ stdio (JSON-RPC 2.0)
   ▼
Node.js MCP Server (godot)                 ← 固定端口 6510，token 鉴权，Godot 关闭时自退
   │ WebSocket (JSON-RPC 2.0) + auth token
   ▼
Godot Editor Plugin (addons/godot_mcp)
   ├── command_router → scene/node/script/editor/project/runtime 模块
   └── mcp_runtime autoload（运行时读属性/截图，走文件 IPC）

连接与鉴权

• 端口默认 6510，server 用 GODOT_MCP_PORT 覆盖；addon 端固定 FIXED_PORT = 6510（或 res://godot_mcp_config.json 的 port）。

• token 存于项目根 .godot/mcp_token（0600，git 忽略）。server 启动时若无则生成，addon 从同路径读取后以 auth 消息上报，server 校验通过才回 server_hello。

• 一个 server 同时只服务一个项目（GODOT_MCP_PROJECT）。换项目改 mcp.json 的该 env 即可。

安装

1. Server

改 agents/cursor/mcp.json（已在仓库内）：

{
  "mcpServers": {
    "godot": {
      "command": "/Users/max/.local/node/bin/node",
      "args": ["/Users/max/Documents/Agent/agents/mcp/godot/godot-mcp-lite/server/dist/index.js"],
      "env": {
        "GODOT_MCP_PORT": "6510"
      }
    }
  }
}

项目自动跟随：无需写死 GODOT_MCP_PROJECT。server 启动时扫描运行中的 Godot 编辑器进程，取它打开的 --path 项目；没有就用 cwd 向上找。因此它会自动跟随当前打开的 Godot 项目，切项目不用改配置。仅当需要显式指定某项目时，才设 GODOT_MCP_PROJECT（优先级最高）。

改动后需在 Cursor 的 Settings → MCP 里刷新/重启该 server。

2. Godot 插件

把 addons/godot_mcp/ 拷贝到你的 Godot 项目 addons/ 下，然后 Project → Project Settings → Plugins 设为 Active。首次打开时会自动注入 MCPRuntime autoload。

构建（改 TS 源码后）

cd godot-mcp-lite/server && npm install && npx tsc

日志（调试用）

Server 把运行日志写入文件，便于 MCP 排查，同时自动按大小滚动 + 数量/天数清理，避免磁盘膨胀。

• 默认路径：server/logs/godot-mcp.log（GODOT_MCP_LOG_DIR 可改）

• 内容含：启动、端口监听、连接/鉴权、工具调用失败、白名单 drop、关闭等关键事件

• 级别：默认 info；设置 GODOT_MCP_DEBUG 或 GODOT_MCP_LOG_LEVEL=debug 可看更细（含白名单 drop 噪音）

日志写入失败的异常被静默吞掉，不会影响 server 运行。

保留的工具集（43 个）

• 项目：get_project_info、get_project_settings

• 场景：get_scene_tree、create_scene、open_scene、play_scene、stop_scene、save_scene、get_loaded_scenes、set_main_scene、get_main_scene、close_scene 等

• 节点：add_node、delete_node、move_node、update_property、get_node_properties、rename_node、get_node_groups 等

• 校验/读取：validate_script、read_script、get_open_scripts

• 日志/错误：get_editor_errors、get_output_log、clear_output、get_diagnostics

• 运行时（只读/截图）：get_game_scene_tree、get_game_node_properties、capture_frames、get_game_screenshot

默认不注册：execute_editor_script、execute_game_script、delete_scene、set_game_node_property、输入模拟、录制回放、批量写、路径遍历类。

安全模型

• 仅监听 127.0.0.1 固定端口，未带有效 token 的连接一律 1008 关闭。

• Token 不进 git，权限 0600，目录在 .godot/。

• 工具白名单在 server（TOOL_ALLOWLIST）与 addon（plugin.gd module_paths）双层落实；危险工具既不注册也不加载。

• Godot 打开期间 server 保持存活（不做空闲超时，避免会话中途掉线）；检测到绑定的 Godot 编辑器进程关闭后退出，不留常驻进程。

相关

• 上游：KeeVeeG/godot-mcp（MIT，本版仅精调其 server/addon）

• 本地资源：agents/mcp/godot/godot-mcp-lite/