使用说明

Godot MCP-高级AI桥

🎮 全功能的Godot编辑器集成+离线项目分析，用于AI辅助游戏开发

此MCP服务器使Claude（或任何兼容MCP的AI）能够：

实时操作Godot编辑器 -创建节点、修改场景、放置对象
离线了解您的项目 -分析脚本、查找依赖关系、搜索代码
按比例进行水平设计 -分散物体、地形感知放置、批量操作

建筑

┌─────────────┐           ┌─────────────────────────────────────────┐
│             │           │            MCP Server (Python)          │
│   Claude    │◄─stdio───►│  ┌─────────────┐  ┌─────────────────┐   │
│             │           │  │ Live Tools  │  │ Offline Analysis│   │
└─────────────┘           │  │ (HTTP→Godot)│  │ (File Parsing)  │   │
                          │  └──────┬──────┘  └─────────────────┘   │
                          └─────────┼───────────────────────────────┘
                                    │ HTTP :6550
                          ┌─────────▼───────────┐
                          │   Godot Editor      │
                          │   Claude Bridge     │
                          │   (@tool plugin)    │
                          └─────────────────────┘

快速开始

1.安装Godot插件

复制 godot-plugin/addons/claude_bridge/ 对于您的项目：

your_project/
└── addons/
    └── claude_bridge/
        ├── plugin.cfg
        └── plugin.gd

启用： 项目→ 项目设置→ 插件→ 克劳德·布里奇

2.安装Python依赖项

cd mcp-server
pip install -r requirements.txt

3.配置克劳德桌面

添加到 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "godot": {
      "command": "python",
      "args": ["C:\\Projects\\mcp-Gdot\\mcp-server\\server.py"]
    }
  }
}

重新启动克劳德桌面。

工具类别

🔌 连接和设置

工具	说明
`godot_ping`	检查Godot是否已连接
`godot_set_project`	设置离线分析的项目路径

🌳 场景树（直播）

工具	说明
`godot_get_scene_tree`	获取完整的节点层次结构
`godot_get_flat_nodes`	带职位的平面列表
`godot_open_scene`	打开场景文件
`godot_save_scene`	保存当前场景

🎯 选择

工具	说明
`godot_get_selected`	获取所选节点
`godot_select_nodes`	按路径选择
`godot_select_by_type`	选择所有类型
`godot_select_by_group`	按组选择

➕ 节点操作

工具	说明
`godot_create_node`	创建节点
`godot_create_many_nodes`	批量创建
`godot_delete_node`	删除节点
`godot_duplicate_node`	带偏移的复制
`godot_get_properties`	读取节点属性
`godot_set_property`	设置属性
`godot_set_multiple_properties`	一次设置多个
`godot_add_to_group`	添加到组
`godot_remove_from_group`	从组中删除

📦 场景实例化

工具	说明
`godot_instantiate_scene`	实例化一个打包场景
`godot_instantiate_many`	批量实例化

🗺️ 水平设计和地形

工具	说明
`godot_get_terrain_height`	x、z高度的光线投射
`godot_get_terrain_heights`	批量高度查询
`godot_scatter_objects`	带斜率过滤的智能散射
`godot_place_along_path`	沿航路点放置
`godot_place_grid`	网格布局

⚡ 批量操作

工具	说明
`godot_batch_set_property`	在多个节点上设置属性
`godot_batch_add_to_group`	向组中添加多个
`godot_batch_delete_by_type`	删除所有类型
`godot_batch_delete_by_group`	删除组中的所有内容
`godot_batch_replace_mesh`	在项目范围内交换网格资源

🔍 搜索

工具	说明
`godot_search_nodes`	多条件搜索
`godot_find_by_type`	按节点类型查找
`godot_find_by_group`	按组查找
`godot_find_by_name`	按名称模式查找

🐛 调试

工具	说明
`godot_run_scene`	播放当前场景
`godot_stop_running`	停止运行游戏

💻 脚本执行

工具	说明
`godot_execute`	运行任意GDScript
`godot_execute_on_selected`	在每个选定节点上运行代码

离线分析（无需Godot！）

这些工具直接解析您的项目文件——Godot不需要运行。

工具	说明
`analyze_project_info`	project.godot信息、自动加载、输入
`analyze_scan_scripts`	扫描所有.gd文件
`analyze_scan_scenes`	扫描所有.tscn文件
`analyze_script`	对一个脚本的深入分析
`analyze_scene`	对一个场景的深入分析
`analyze_find_nodes_by_type`	查找所有场景中的节点类型
`analyze_find_nodes_by_group`	查找所有场景中的组
`analyze_find_script_usages`	搜索函数/变量/信号
`analyze_find_signal_connections`	查找信号连接
`analyze_dependency_graph`	构建依赖关系树
`analyze_find_orphans`	查找未引用的资源
`analyze_search_in_files`	Regex跨文件搜索

示例提示

关卡设计

"Scatter 100 oak trees in a 200m radius around the player spawn,
 avoid slopes over 30 degrees, minimum 5m spacing, random Y rotation"

"Place torches along the path from the entrance to the boss room,
 10 meters apart, aligned to face the path direction"

"Create a 5x5 grid of market stalls starting at (100, 0, 100)"

批量操作

"Set all WildlifeSpawner nodes to respawn_time = 300"

"Delete all nodes in the 'debug' group"

"Replace all instances of old_tree.glb with new_tree.glb"

项目分析

"Find all scripts that use the 'damage_dealt' signal"

"What functions does the PlayerCombat class have?"

"Show me the dependency graph - what loads what"

"Find orphaned scenes that aren't used anywhere"

定制操作

"Run this code on all selected nodes: node.modulate = Color.RED"

"Execute: print(scene_root.get_children())"

扩展插件

添加新端点

在中添加处理程序 plugin.gd:

func _my_handler(data: Dictionary) -> Dictionary:
    # Do stuff
    return {"success": true, "data": result}

添加路线 _route_request():

"my/endpoint": return _my_handler(data)

添加工具 server.py:

Tool(
    name="godot_my_tool",
    description="Does cool stuff",
    inputSchema={...}
)

添加到端点映射 call_tool().

故障排除

“无法连接到Godot”

Godot正在运行吗？
插件是否已启用？检查项目设置→ 插件
检查输出面板上的“Claude Bridge:服务器正在监听…”

离线分析不起作用

你打电话来了吗 godot_set_project 第一？
路径是否正确（应包含project.godot）？

地形光线投射不返回命中值

你的地形有碰撞吗？
碰撞层是否正确？

许可证

麻省理工学院-随心所欲！ 🚀