dvcrn Godot MCP Server 集成指南
概述
Godot MCP Server 是一个强大的插件，让 AI 助手能够直接与 Godot 编辑器交互，实现 AI 驱动的游戏开发。
核心能力
- 场景管理 - 创建、打开、保存场景
- 节点操作 - 添加、删除、移动、修改节点
- 脚本编辑 - 创建和修改 GDScript 脚本
- 资源管理 - 加载和创建游戏资源
- 文件系统 - 浏览项目、读写文件
- 编辑器控制 - 选中对象、撤销重做
- 调试工具 - 查看日志、运行时信息
安装配置
1. 安装插件
# 克隆仓库
git clone https://github.com/DaxianLee/godot-mcp.git
# 复制到项目
cp -r godot-mcp/addons/godot_mcp /path/to/your/project/addons/
2. 启用插件
在 Godot 编辑器中：
项目 -> 项目设置 -> 插件- 找到 Godot MCP Server
- 点击启用
3. 配置 MCP 服务器
默认配置：
- 端口: 3000
- 地址:
http://127.0.0.1:3000/mcp - 自动启动: 开启
在 GodotMCP 面板中可以：
- 查看服务器状态
- 管理可用工具
- 配置 AI 客户端
AI 客户端配置
IDE 编辑器（一键配置）
Trae CN
# 配置文件位置
# macOS: ~/Library/Application Support/Trae CN/User/mcp.json
# Windows: %APPDATA%\Trae CN\User\mcp.json
# Linux: ~/.config/Trae CN/User/mcp.json
# 在 GodotMCP 面板中点击「一键配置」即可
Cursor
# 配置文件位置
~/.cursor/mcp.json
# 在 GodotMCP 面板中点击「一键配置」即可
Windsurf
# 配置文件位置
~/.codeium/windsurf/mcp_config.json
# 在 GodotMCP 面板中点击「一键配置」即可
CLI 工具（命令配置）
Claude CLI (Claude Code)
# 用户级配置（全局）
claude mcp add --scope user --transport http godot-mcp http://127.0.0.1:3000/mcp
# 项目级配置（当前项目）
claude mcp add --scope project --transport http godot-mcp http://127.0.0.1:3000/mcp
Codex CLI
# 用户级
codex mcp add --scope user --transport http godot-mcp http://127.0.0.1:3000/mcp
# 项目级
codex mcp add --scope project --transport http godot-mcp http://127.0.0.1:3000/mcp
Gemini CLI
# 用户级
gemini mcp add --scope user --transport http godot-mcp http://127.0.0.1:3000/mcp
# 项目级
gemini mcp add --scope project --transport http godot-mcp http://127.0.0.1:3000/mcp
工具分类
核心工具
场景工具 (Scene)
scene_create - 创建新场景
scene_open - 打开指定场景
scene_save - 保存当前场景
scene_get_tree - 获取场景树结构
scene_get_current - 获取当前场景信息
使用示例：
用户: 创建一个新场景，命名为 "Level1"
AI: [调用 scene_create {"name": "Level1"}]
已创建场景 Level1
用户: 添加一个 Sprite2D 节点
AI: [调用 node_add {"type": "Sprite2D", "name": "Player"}]
已添加 Sprite2D 节点到场景
节点工具 (Node)
node_add - 添加新节点
node_delete - 删除节点
node_get - 获取节点信息
node_set_property - 设置节点属性
node_get_property - 获取节点属性
node_move - 移动节点位置
node_rename - 重命名节点
node_duplicate - 复制节点
node_find - 查找节点
使用示例：
用户: 将 Player 节点的位置设置为 (100, 200)
AI: [调用 node_set_property {
"node": "Player",
"property": "position",
"value": {"x": 100, "y": 200}
}]
已设置 Player 位置为 (100, 200)
脚本工具 (Script)
script_create - 创建新脚本
script_read - 读取脚本内容
script_write - 写入脚本内容
script_attach - 附加脚本到节点
使用示例：
用户: 为 Player 节点创建一个脚本
AI: [调用 script_create {
"name": "player.gd",
"template": "CharacterBody2D"
}]
[调用 script_attach {
"node": "Player",
"script": "res://scripts/player.gd"
}]
已创建并附加脚本
资源工具 (Resource)
resource_load - 加载资源
resource_create - 创建资源
resource_save - 保存资源
文件系统工具 (Filesystem)
filesystem_list - 列出目录内容
filesystem_read - 读取文件
filesystem_write - 写入文件
filesystem_delete - 删除文件
项目工具 (Project)
project_get_info - 获取项目信息
project_get_settings - 获取项目设置
编辑器工具 (Editor)
editor_get_selection - 获取当前选中
editor_select_node - 选中指定节点
editor_undo_redo - 撤销/重做操作
调试工具 (Debug)
debug_get_logs - 获取调试日志
视觉工具
材质工具 (Material)
material - 创建和配置材质
使用示例：
用户: 创建一个发光材质
AI: [调用 material {
"type": "StandardMaterial3D",
"emission": {"enabled": true, "color": "#00FF00"}
}]
已创建发光材质
着色器工具 (Shader)
shader - 着色器参数管理
灯光工具 (Lighting)
lighting - 场景灯光配置
粒子工具 (Particle)
particle - 粒子效果创建
2D 工具
瓦片地图工具 (TileMap)
tilemap - TileMap 编辑
使用示例：
用户: 创建一个 TileMap 并设置瓷砖
AI: [调用 node_add {"type": "TileMap", "name": "Ground"}]
[调用 tilemap {
"action": "set_cell",
"coords": [(0, 0), (1, 0), (2, 0)],
"tile_id": 1
}]
已创建 TileMap 并铺设瓷砖
几何体工具 (Geometry)
geometry - 2D 几何图形
游戏玩法工具
物理工具 (Physics)
physics - 物理体和碰撞配置
使用示例：
用户: 为 Player 添加碰撞形状
AI: [调用 node_add {
"type": "CollisionShape2D",
"parent": "Player"
}]
[调用 physics {
"node": "Player/CollisionShape2D",
"shape": "CapsuleShape2D",
"radius": 10,
"height": 20
}]
已添加碰撞形状
导航工具 (Navigation)
navigation - 导航网格和寻路
音频工具 (Audio)
audio - 音频播放和配置
实用工具
UI 工具
ui - 用户界面组件
信号工具 (Signal)
signal - 信号连接管理
分组工具 (Group)
group - 节点分组管理
工作流程示例
示例 1: 创建完整场景
用户: 创建一个包含玩家、敌人和地形的场景
AI 执行步骤:
1. [scene_create {"name": "GameScene"}]
2. [node_add {"type": "Node2D", "name": "Entities"}]
3. [node_add {"type": "CharacterBody2D", "name": "Player", "parent": "Entities"}]
4. [node_add {"type": "Sprite2D", "name": "Sprite", "parent": "Player"}]
5. [script_create {"name": "player.gd"}]
6. [script_attach {"node": "Player", "script": "res://player.gd"}]
7. [node_add {"type": "CharacterBody2D", "name": "Enemy", "parent": "Entities"}]
8. [node_add {"type": "TileMap", "name": "Ground"}]
9. [scene_save]
完成！已创建包含玩家、敌人和地形的场景。
示例 2: 配置玩家物理
用户: 为玩家添加物理和碰撞检测
AI 执行步骤:
1. [node_add {"type": "CollisionShape2D", "parent": "Player"}]
2. [physics {
"node": "Player/CollisionShape2D",
"shape": "CapsuleShape2D",
"radius": 10,
"height": 30
}]
3. [script_write {
"path": "res://player.gd",
"content": "extends CharacterBody2D\n\nconst SPEED = 300.0\nconst JUMP_VELOCITY = -400.0\n\nvar gravity = ProjectSettings.get_setting(\"physics/2d/default_gravity\")\n\nfunc _physics_process(delta):\n # Add the gravity.\n if not is_on_floor():\n velocity.y += gravity * delta\n \n # Handle Jump.\n if Input.is_action_just_pressed(\"ui_accept\") and is_on_floor():\n velocity.y = JUMP_VELOCITY\n \n # Get the input direction and handle the movement/deceleration.\n var direction = Input.get_axis(\"ui_left\", \"ui_right\")\n if direction:\n velocity.x = direction * SPEED\n else:\n velocity.x = move_toward(velocity.x, 0, SPEED)\n \n move_and_slide()"
}]
完成！已为玩家配置物理系统。
示例 3: 批量创建敌人
用户: 在场景中放置 5 个敌人
AI 执行步骤:
1. [scene_open {"path": "res://scenes/game.tscn"}]
2. [node_add {"type": "Node2D", "name": "Enemies"}]
3. [node_duplicate {"node": "Enemy", "count": 4}]
4. [node_set_property {"node": "Enemy2", "property": "position", "value": {"x": 200, "y": 0}}]
5. [node_set_property {"node": "Enemy3", "property": "position", "value": {"x": 400, "y": 0}}]
6. [node_set_property {"node": "Enemy4", "property": "position", "value": {"x": 600, "y": 0}}]
7. [node_set_property {"node": "Enemy5", "property": "position", "value": {"x": 800, "y": 0}}]
8. [scene_save]
完成！已创建 5 个敌人并放置在场景中。
高级用法
1. 自动化测试
# 创建测试场景
用户: 创建一个测试场景，包含多个物理对象
AI: [创建场景和物理对象]
[配置物理参数]
[添加调试可视化]
测试场景已就绪
2. 资源批处理
# 批量处理资源
用户: 将所有纹理的 filter 模式改为 Nearest
AI: [filesystem_list {"path": "res://textures"}]
[循环每个纹理]
[resource_load]
[修改 filter_mode]
[resource_save]
已更新所有纹理设置
3. 代码生成
# 生成游戏代码
用户: 为所有敌人节点生成 AI 脚本
AI: [node_find {"pattern": "Enemy*"}]
[为每个敌人创建脚本]
[根据类型生成 AI 逻辑]
[附加脚本]
已生成所有 AI 脚本
故障排除
服务器无法启动
检查:
1. 端口 3000 是否被占用
2. 防火墙是否阻止
3. Godot 版本是否兼容
解决:
- 更改端口号
- 关闭防火墙或添加例外
- 升级到 Godot 4.x
AI 客户端无法连接
检查:
1. MCP 服务器是否运行（绿色状态）
2. 配置文件中的端口号是否正确
3. AI 客户端是否重启
解决:
- 重启 MCP 服务器
- 检查配置文件
- 重启 AI 客户端
工具调用失败
检查:
1. 节点路径是否正确
2. 属性名是否正确
3. 参数类型是否匹配
解决:
- 使用 scene_get_tree 查看场景结构
- 使用 node_get 查看可用属性
- 检查文档中的参数格式
最佳实践
1. 场景组织
推荐结构:
Scene
├── Entities
│ ├── Player
│ └── Enemies
├── Environment
│ ├── TileMaps
│ └── Props
└── UI
└── HUD
2. 命名规范
- 节点名: PascalCase (Player, Enemy)
- 脚本名: snake_case (player.gd, enemy_ai.gd)
- 场景名: snake_case (level_1.tscn, main_menu.tscn)
3. 批量操作
优先使用批量工具:
- node_duplicate (批量复制)
- tilemap (批量铺设)
- filesystem_list (批量文件操作)
4. 错误处理
始终检查操作结果:
1. scene_get_tree (验证场景结构)
2. node_get (验证节点存在)
3. debug_get_logs (查看错误日志)
多语言支持
插件支持 9 种语言：
- English
- 简体中文
- 繁體中文
- 日本語
- Русский
- Français
- Português
- Español
- Deutsch
在 GodotMCP 面板的「服务器」标签中切换语言。
参考资源
- MCP 协议: references/mcp-protocol.md
- API 文档: references/api-reference.md
- 示例代码: references/examples.md
- 故障排除: references/troubleshooting.md
许可证
非商业使用许可证
允许:
- 个人学习和研究
- 非商业开源项目
- 教育和教学
禁止:
- 商业用途
- 未经授权的再分发
商业使用请联系作者: LIDAXIAN (微信: lidaxian-AI)
贡献
欢迎提交 Issue 和 Pull Request！