AI导哈

Godot游戏引擎MCP服务器

一个连接Claude Code与Godot 4.6游戏引擎的MCP服务器，支持从终端运行项目、截图、检查编辑场景树、点击UI等功能。

  • by slangwald
  • GDScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 slangwald/godot-mcp

使用说明

Godot MCP服务器

一 MCP（模型上下文协议） 连接的服务器 克劳德代码 到 戈多4.6 游戏引擎。

Claude可以运行你的项目，截图，检查和编辑场景树，点击UI，迭代你的游戏——所有这些都可以在终端上完成。

https://github.com/user-attachments/assets/99a70dab-0ff5-4597-809b-25a5a3e1c3e0

它能做什么？

编辑器工具（端口9500）

工具 说明
get_scene_tree 在编辑器中检查完整的节点层次结构
get_node_properties 读取任何节点上的任何属性
modify_node 更改节点属性（文本、位置、颜色等）
create_node 向场景中添加新节点
delete_node 从场景中删除节点
set_resource 创建资源（网格、材质等）并将其分配给节点
attach_script 创建内联GDScript并将其附加到节点
set_script 将现有的.gd文件分配给节点
get_signals 列出节点上的所有信号及其连接
connect_signal 连接两个节点之间的信号连接
instantiate_scene 添加一个现有的.tscn作为子节点
list_resources 列出所有项目文件（.tscn、.gd、.tres等）
run_project 从编辑器启动游戏
run_scene 运行特定场景（而不仅仅是主场景）
stop_project 停止跑步游戏
save_scene 保存当前场景
open_scene 在编辑器中打开场景文件
get_editor_state 检查哪个场景是打开的，游戏是否正在运行
get_output 读取最近的Godot编辑器日志输出（打印、错误）
undo / redo 撤消或重做上次编辑器操作

游戏工具（端口9501）

工具 说明
screenshot 将游戏视口捕获为PNG图像
click 在视口坐标处模拟鼠标点击
get_runtime_tree 在游戏运行时检查实时场景树

运作原理

Claude Code <--stdio--> Python MCP Server <--TCP:9500--> Godot Editor Plugin
                                                              |
                                                         Running Game <--TCP:9501--> Python MCP Server
  • Python MCP服务器 --将Claude代码（通过stdio）连接到Godot（通过TCP）。这就是克劳德所说的。
  • 编辑器插件 --在Godot编辑器中运行。监听9500端口。处理场景树操作、运行/停止项目、保存。
  • 游戏自动加载 --注入跑步游戏。监听端口9501。捕获屏幕截图，模拟输入，并显示运行时场景树。

截图以base64编码的PNG格式通过TCP发送，没有临时文件，也没有文件系统依赖关系。

先决条件

设置

1.在Godot中克隆并打开

git clone https://github.com/slangwald/godot-mcp.git
cd godot-mcp

打开 project.godot 在Godot 4.6中。MCP网桥插件已预先配置，将自动激活。

2.使用Claude Code注册MCP服务器

claude mcp add godot-mcp -- uv run --directory /absolute/path/to/godot-mcp/mcp python godot_mcp_server.py

注： 使用完整的绝对路径 mcp/ 目录。这只需要做一次。

3.启动新的Claude Code会话

MCP服务器在启动时加载，因此在注册后启动一个新的会话：

claude

您应该看到可用的Godot工具。打开Godot编辑器，尝试：

> Use get_scene_tree to show me the current scene
> Run the project and take a screenshot

添加到您自己的Godot项目

MCP服务器未与示例应用程序绑定。要将其用于任何Godot 4.6项目，请执行以下操作：

  1. 复制插件 --复制 addons/mcp_bridge/ 进入你的项目 addons/ 目录

  2. 复制游戏自动加载 --复制 mcp_bridge_game.gd 到您的项目根目录

  3. 启用插件 --在Godot中：项目>项目设置>插件>启用“MCP桥”

  4. 添加自动加载 --在Godot中：项目>项目设置>自动加载>添加 mcp_bridge_game.gd 作为 McpBridgeGame

    或手动添加到您的 project.godot:

    [autoload]
McpBridgeGame="*res://mcp_bridge_game.gd"

[editor_plugins]
enabled=PackedStringArray("res://addons/mcp_bridge/plugin.cfg")

  5. 注册MCP服务器 使用Claude Code（与上述命令相同，指向此仓库 mcp/ 目录）

示例应用程序

这 examples/ 目录包含三个完全使用MCP工具构建的演示：

  • 看板 (examples/kanban/)--带有三列和持久存储的拖放任务板
  • 旋转立方体 (examples/cube/)--具有旋转立方体、动态照明和环境效果的3D场景
  • Cookie点击器 (examples/cookie_clicker/)--带有自动点击器和升级商店的空闲点击器游戏

发射器(examples/launcher/)通过一个持久的导航栏将它们连接在一起，以便在场景之间切换。

平台支持

适用于 macOS, 视窗，以及 Linux所有通信都使用本地主机TCP套接字和base64编码的有效载荷，没有特定于平台的路径或依赖关系。

TCP协议

编辑器插件（端口9500）和游戏自动加载（端口9501）都使用相同的简单协议：

  • 请求： JSON与a "cmd" 键，换行终止
  • 答复： JSON，换行符终止
  • 连接 是短暂的（连接>发送>接收>关闭）

例子：

{"cmd": "get_scene_tree"}

{"ok": true, "tree": {"name": "Main", "type": "Control", "path": ".", "children": [...]}}

这意味着您还可以从任何TCP客户端使用Godot网桥，而不仅仅是通过MCP服务器。

故障排除

“无法连接到端口9500上的Godot编辑器”

  • 确保此项目（或启用了MCP Bridge插件的项目）打开了Godot编辑器

“无法连接到端口9501上的Godot游戏”

  • 游戏必须运行。呼叫 run_project 第一。

Claude代码中未显示工具

  • MCP服务器在会话启动时加载。开始新的 claude 注册后的会话。
  • 证实 claude mcp list --你应该看看 godot-mcp: connected

屏幕截图返回错误

  • 游戏必须正在运行，并且至少渲染了一帧。等一下 run_project 打电话之前 screenshot.

许可证

麻省理工学院

相关 MCP