Godot MCP Pro

168 个 AI 驱动的 Godot 4 编辑器工具 — 将您的 AI 助手（Claude、Cursor、Cline、Copilot）连接到 Godot，并使用自然语言构建游戏。

工作原理

在 5 分钟内将您的 AI 助手连接到 Godot。

1. 安装插件

将 addons/godot_mcp/ 复制到您的 Godot 项目中。在 项目 > 项目设置 > 插件 中启用它。该插件会自动在编辑器内启动一个 WebSocket 服务器。

2. 构建 MCP 服务器

cd server
npm install && npm run build

这将编译 TypeScript MCP 服务器，该服务器将您的 AI 客户端连接到 Godot 插件。

3. 开始使用 AI 构建

将服务器添加到您的 AI 客户端的 MCP 配置中。打开 Godot，您的 AI 助手现在可以实时访问 168 个工具 — 创建场景、编辑脚本、模拟输入以及分析正在运行的游戏。

MCP 客户端配置

Claude Code / Claude Desktop

添加到 .claude/mcp.json：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

VS Code / Cursor

添加到 .vscode/mcp.json：

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["./server/dist/index.js"]
    }
  }
}

任何 stdio MCP 客户端

node server/dist/index.js

服务器使用 MCP 协议通过 stdio (stdin/stdout) 进行通信。

自动化设置（推荐）

cd server
npm run run

这将自动执行以下操作：

构建 MCP 服务器
检测父文件夹中的 project.godot（或 GODOT_PROJECT_PATH）
将插件同步到 addons/godot_mcp
在 project.godot 中启用插件
创建 MCP 配置文件
同步 AI 上下文文件

工具类别

#	类别	工具	亮点
1	项目	7	设置读写，UID 转换
2	场景	9	创建、打开、播放、停止、实例化、保存
3	节点	14	支持撤销/重做的添加/删除/重命名/移动，信号，组
4	脚本	8	CRUD，附加，验证，带行号的搜索
5	编辑器	10	截图，执行 GDScript，错误日志，重载
6	输入	7	键盘、鼠标、动作模拟、序列
7	运行时	19	游戏检查，帧捕获，录制/回放，UI
8	动画	6	CRUD，轨道，关键帧
9	动画树	8	状态机，转换，混合树
10	TileMap	6	单元格操作（Godot 4.3+ 使用 TileMapLayer）
11	3D 场景	6	网格基元，.glb 导入，灯光预设，PBR
12	物理	6	自动 2D/3D 碰撞，射线检测，层
13	粒子	5	GPU 粒子 + 火焰/烟雾/雨/雪/火花预设
14	导航	6	区域，代理，烘焙，寻路
15	音频	6	播放器（自动 2D/3D），总线效果链
16	主题/UI	6	StyleBoxFlat，颜色/常量/字体覆盖
17	着色器	6	模板 (canvas_item, spatial, particles, sky)
18	资源	6	.tres CRUD，自动加载管理
19	批处理	8	按类型查找，批量设置，依赖分析
20	测试	6	自动化场景，断言，压力测试
21	分析	4	场景复杂度，信号流，未使用的资源
22	性能分析	2	FPS，内存，物理，渲染监视器
23	导出	3	预设列表，构建命令
	总计	168	+ 4 个核心连接工具

主要功能

🧠 智能类型解析

无需手动构建复杂的对象。属性值会自动转换：

"Vector2(100, 200)"  → Vector2(100, 200)
"Color(1, 0, 0)"    → Color(1, 0, 0)
"#ff0000"            → Color(1, 0, 0)
"Color.RED"          → Color(1, 0, 0)
"true"               → true
"42"                 → 42

♻️ 所有变更均支持撤销/重做

每一个 add_node、delete_node、update_property、rename_node 和 move_node 操作都会通过 Godot 的 UndoRedo 系统。您的用户可以 Ctrl+Z 撤销任何 AI 操作。

🎯 自动 2D/3D 检测

物理实体、碰撞形状、音频播放器、粒子和导航节点会自动检测父级是 2D 还是 3D — 每次都能创建正确的类型。

🔥 内置预设

灯光：太阳、室内、戏剧性、聚光灯
粒子：火焰、烟雾、雨、雪、火花
着色器：canvas_item, spatial, particles, sky 模板
音频效果：混响、延迟、压缩器、均衡器、失真、合唱、移相器

快速示例

AI: godot_connect
AI: create_scene path="res://scenes/level.tscn" rootType="Node2D"
AI: add_node type="CharacterBody2D" name="Player" parentPath="."
AI: add_node type="Sprite2D" name="Sprite" parentPath="Player"
AI: update_property path="Player/Sprite" property="texture" value="res://icon.svg"
AI: setup_collision path="Player" shapeType="rectangle" size="Vector2(32, 32)"
AI: create_script path="res://scripts/player.gd" content="extends CharacterBody2D..."
AI: attach_script nodePath="Player" scriptPath="res://scripts/player.gd"
AI: save_scene
AI: play_scene
AI: simulate_key key="Space"
AI: get_game_screenshot
AI: stop_scene

架构

server/src/
├── index.ts           TypeScript MCP server (stdio transport)
├── toolCatalog.ts     168 tool definitions with input schemas
└── godotBridge.ts     WebSocket client → Godot editor

addons/godot_mcp/
├── plugin.gd          Plugin entry point
├── websocket_server.gd Local WebSocket server (port 6505)
├── command_router.gd  Loads 20 handler modules, dispatches commands
└── commands/
    ├── base_commands.gd        Shared utilities (type parser, undo, I/O)
    ├── type_parser.gd          Smart string→Godot type conversion
    ├── undo_helper.gd          UndoRedo wrapper
    ├── core_commands.gd        Project, scene, node, script, editor (47 handlers)
    ├── editor_commands.gd      Screenshots, execute script (4)
    ├── input_commands.gd       Input simulation (7)
    ├── runtime_commands.gd     Game inspection & UI (15)
    ├── animation_commands.gd   Animation CRUD (6)
    ├── animation_tree_commands.gd  State machine & blend tree (8)
    ├── tilemap_commands.gd     Tile operations (6)
    ├── scene3d_commands.gd     3D scene building (6)
    ├── physics_commands.gd     Physics & collision (6)
    ├── particles_commands.gd   GPU particles + presets (5)
    ├── navigation_commands.gd  Nav regions & pathfinding (6)
    ├── audio_commands.gd       Audio players & bus effects (6)
    ├── theme_commands.gd       Theme & UI styling (6)
    ├── shader_commands.gd      Shader management (4)
    ├── resource_commands.gd    Resource & autoload (6)
    ├── batch_commands.gd       Batch operations (8)
    ├── testing_commands.gd     Testing & QA (5)
    ├── analysis_commands.gd    Code analysis (4)
    ├── profiling_commands.gd   Performance profiling (2)
    └── export_commands.gd      Export management (3)

网桥协议

基于 WebSocket 的 JSON-RPC 2.0 (ws://127.0.0.1:6505)：

→ { "jsonrpc": "2.0", "id": 1, "method": "add_node", "params": { "type": "Sprite2D", "name": "Player" } }
← { "jsonrpc": "2.0", "id": 1, "result": { "tool": "add_node", "data": { "path": "/root/Main/Player" } } }

覆盖网桥 URL：GODOT_WS_URL=ws://127.0.0.1:6505 node server/dist/index.js

要求

Godot 4.2+ (TileMapLayer 建议使用 4.3+)
Node.js 18+
任何兼容 MCP 的 AI 客户端

AI 代理上下文文件

当部署到 Godot 项目时，这些上下文文件有助于 AI 助手理解可用的工具：

文件	用途	使用者
`addons/godot_mcp/skills.md`	包含工作流的完整 168 个工具参考	所有 AI 代理
`AGENTS.md`	架构 + 功能摘要	Codex, Gemini, 代理
`CLAUDE.md`	快速参考 + 构建命令	Claude Code
`.github/copilot-instructions.md`	Copilot 特定指令	GitHub Copilot

Godot MCP Bridge