Godot MCP Plugin

此插件的功能已整合到https://github.com/rosskarchner/godot-mcp

Godot MCP服务器插件

Godot Engine 4.x的完整模型上下文协议（MCP）服务器实现，使Claude等AI代理能够直接检查和操纵Godot编辑器，并通过HTTP运行游戏。

特性

• 基于HTTP的MCP服务器：支持JSON-RPC 2.0协议的强大HTTP服务器
• 场景管理：检查场景树、加载/保存场景、导航层次结构
• 节点操作：实时创建、删除、重命名节点、修改属性
• 脚本管理：附加/分离脚本，读取源代码，执行GDScript
• 资源访问：列出项目资源，读取文件内容
• 项目配置：从project.godot获取/设置项目设置
• 输入管理：配置输入映射、操作和键绑定
• 输入模拟：将模拟的键盘、鼠标和游戏手柄事件发送到正在运行的游戏
• 视觉反馈：使用可配置的分辨率和区域裁剪捕获视口的屏幕截图
• 场景回放：以编程方式启动/停止场景播放
• 编辑器输出：读取编辑器日志，包括print（）语句、错误和警告
• CORS支持：为基于web的客户端内置CORS标头
• 可配置的：端口、身份验证、限制的编辑器设置

快速开始

最简单的开始方法是使用包含的示例项目：

# From the repository root:
./setup_example.sh
# Then open ./example_project in Godot Engine

示例项目附带了预先配置好的插件，可以随时使用。

安装

对于您自己的项目：

1. 复制 addons/mcp_server/ 将目录放入Godot项目的 addons/ 文件夹
2. 在Godot编辑器中打开您的项目
3. 首选 项目→ 项目设置→ 插件
4. 启用“MCP服务器”插件
5. 服务器将在端口8765（可配置）上自动启动

配置

该插件在以下位置添加设置 编辑→ 编辑器设置→ MCP服务器:

• 端口：服务器端口（默认值：8765）
• 自动启动：加载编辑器时启动服务器（默认值：true）
• 身份验证令牌：可选身份验证令牌
• 最大树深度：场景树查询的最大深度（默认值：10）

MCP客户端配置

要将MCP客户端（如Claude Desktop）连接到此服务器，请将以下内容添加到MCP设置配置中：

{
  "mcpServers": {
    "godot": {
      "url": "http://localhost:8765",
      "transport": {
        "type": "http"
      }
    }
  }
}

对于Claude Desktop，此文件通常位于：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

可用工具

场景管理

get_scene_tree

获取当前场景的层次结构。

论据：

• max_depth （可选）：要遍历的最大深度（默认值：10）

例子：

{
  "name": "get_scene_tree",
  "arguments": {
    "max_depth": 5
  }
}

get_current_scene

获取有关当前编辑的场景的信息。

save_scene

将当前场景保存到磁盘。

load_scene

加载其他场景进行编辑。

论据：

• path：场景文件的资源路径（例如。， res://scenes/main.tscn)

节点操作

get_node_info

获取特定节点的详细信息。

论据：

• node_path：到节点的路径（例如。， /root/Node2D/Player)

get_node_properties

列出节点的所有属性及其当前值。

论据：

• node_path：节点路径

set_node_property

在特定节点上设置属性值。

论据：

• node_path：节点路径
• property：属性名称（例如。， position, rotation)
• value：房产的新价值

例子：

{
  "name": "set_node_property",
  "arguments": {
    "node_path": "/root/Player",
    "property": "position",
    "value": [100, 200]
  }
}

create_node

在场景中创建新节点。

论据：

• parent_path：父节点的路径
• node_type：要创建的节点类型（例如。， Node2D, Sprite2D)
• node_name：新节点的名称

delete_node

从场景中删除节点。

论据：

• node_path：要删除的节点的路径

rename_node

重命名节点。

论据：

• node_path：节点路径
• new_name：节点的新名称

脚本操作

get_node_script

将脚本附加到节点。

论据：

• node_path：节点路径

set_node_script

在节点上附加或修改脚本。

论据：

• node_path：节点路径
• script_path：脚本文件的路径（例如。， res://scripts/player.gd)

get_script_source

读取脚本文件的源代码。

论据：

• script_path：脚本文件的路径

资源操作

list_resources

列出项目中的资源。

论据：

• directory （可选）：要列出的目录（默认： res://)
• filter （可选）：文件扩展名过滤器（例如。， .tscn, .gd)

get_screenshot

将当前视口捕获为base64编码的PNG图像。默认分辨率（1280x720）已优化，可保持在25000个令牌以下。支持自定义分辨率限制和区域裁剪。

论据：

• max_width （可选）：最大宽度（像素）（默认值：1280）
• max_height （可选）：最大高度（像素）（默认值：720）
• region_x, region_y, region_width, region_height （可选）：捕获特定视口区域

run_scene

开始播放当前场景。

stop_scene

停止跑步场景。

编辑器工具

godot_editor_get_output

从Godot编辑器的日志文件中读取最近的输出。这涵盖了所有 print() 编辑器和运行游戏的语句、错误、警告和其他输出。

论据：

• max_lines （可选）：要返回的最近日志行的最大数量（默认值：100）
• filter_text （可选）：筛选包含特定文本的日志行（不区分大小写）

例子：

{
  "name": "godot_editor_get_output",
  "arguments": {
    "max_lines": 50,
    "filter_text": "error"
  }
}

使用案例：

• 通过检查print（）输出调试脚本
• 监控开发过程中的错误和警告
• 运行场景后检查游戏输出

项目配置

godot_project_get_setting

从project.godot获取项目设置的值。

论据：

• setting_name：设置的完整路径（例如。， application/config/name)

godot_project_set_setting

在project.godot中设置项目设置值。

论据：

• setting_name：设置的完整路径
• value：新值（支持Vector2、Color等Godot类型）

godot_project_list_settings

列出所有项目设置或按前缀筛选。

论据：

• prefix （可选）：要过滤的类别前缀（例如。， application/, display/)

输入地图管理

godot_input_list_actions

列出所有输入操作及其键/按钮绑定。

godot_input_get_action

获取特定输入操作的详细信息。

论据：

• action_name：输入动作的名称（例如。， ui_accept, jump)

godot_input_add_action

创建新的输入操作。

论据：

• action_name：新操作的名称
• deadzone （可选）：Deadzone用于模拟输入（默认值：0.5）

godot_input_remove_action

删除输入操作。

论据：

• action_name：要删除的操作的名称

godot_input_add_event

将按键、鼠标按钮或游戏手柄事件添加到操作中。

论据：

• action_name：目标操作名称
• event：事件规范（例如。， {"type": "key", "keycode": 32, "pressed": true})

例子：

{
  "name": "godot_input_add_event",
  "arguments": {
    "action_name": "jump",
    "event": {
      "type": "key",
      "keycode": 32,
      "pressed": true
    }
  }
}

godot_input_remove_event

从操作中删除特定的输入事件。

输入事件模拟

godot_input_send_action

向正在运行的游戏发送模拟输入动作事件。

论据：

• action_name：触发动作
• pressed （可选）：是否按下（true）或释放（false）
• strength （可选）：输入强度0.0-1.0

godot_input_send_key

发送键盘按键按下/释放事件。

论据：

• keycode：密钥代码（使用 godot_input_get_constants 值）
• pressed （可选）：是否按下（默认值：true）
• alt_pressed, shift_pressed, ctrl_pressed, meta_pressed （可选）：修改键

godot_input_send_mouse_button

发送鼠标按钮事件。

论据：

• button_index：鼠标按钮（1=左，2=右，3=中）
• pressed （可选）：是否按下
• position_x, position_y （可选）：屏幕位置
• double_click （可选）：是否双击

godot_input_send_mouse_motion

发送鼠标移动事件。

论据：

• position_x, position_y：鼠标位置
• relative_x, relative_y （可选）：相对移动
• velocity_x, velocity_y （可选）：移动速度

godot_input_send_joypad_button

发送游戏手柄按钮按下事件。

论据：

• button_index：按钮索引（使用 godot_input_get_constants)
• pressed （可选）：是否按下
• device （可选）：控制器设备ID（默认值：0）

godot_input_send_joypad_motion

发送游戏手柄轴运动事件。

论据：

• axis：轴索引（使用 godot_input_get_constants)
• axis_value：轴值（摇杆为-1.0到1.0，触发器为0.0到1.0）
• device （可选）：控制器设备ID（默认值：0）

godot_input_get_constants

获取按键代码、鼠标按钮和操纵板控件的常数值。

论据：

• type （可选）：常数类型： all, keys, mouse, joypad （默认值： all)

例子：

{
  "name": "godot_input_get_constants",
  "arguments": {
    "type": "keys"
  }
}

协议实现

该插件通过JSON-RPC 2.0实现了MCP。所有请求和响应都遵循JSON-RPC 2.0规范。

请求格式

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "arg1": "value1"
    }
  },
  "id": 1
}

响应格式

{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "data": "..."
  },
  "id": 1
}

错误格式

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  },
  "id": 1
}

类型转换

该插件处理GDScript类型和JSON之间的转换：

• 矢量2/矢量3 ↔ 数组： [x, y] 或 [x, y, z]
• 颜色 ↔ 对象： {"r": 1.0, "g": 0.5, "b": 0.0, "a": 1.0}
• NodePath 的 ↔ 字符串： "/root/Node2D/Player"
• 资源 ↔ 字符串路径： "res://sprites/player.png"

建筑

该插件分为几个模块：

addons/mcp_server/
├── plugin.cfg                  # Plugin metadata
├── mcp_server.gd              # Main EditorPlugin
├── http_handler.gd            # HTTP server and request handling
├── mcp_protocol.gd            # MCP/JSON-RPC 2.0 implementation
└── tools/                     # Tool implementations
    ├── scene_tools.gd         # Scene management
    ├── node_tools.gd          # Node operations
    ├── script_tools.gd        # Script operations
    └── resource_tools.gd      # Resource and utility tools

安全注意事项

• 服务器正在监听 127.0.0.1 （仅限本地主机）默认情况下
• 身份验证令牌支持可用（可选）
• 出于安全考虑，脚本执行受到限制
• CORS标头允许基于web的客户端
• 所有操作都记录到Godot控制台

⚠️ 重要：在没有适当的身份验证和安全措施的情况下，不要将此服务器暴露在互联网上。它提供了对Godot编辑器和项目文件的直接访问。

故障排除

服务器无法启动

• 检查端口是否已在使用中
• 尝试在编辑器设置中更改端口
• 检查Godot控制台是否有错误消息

工具返回“当前没有打开的场景”

• 确保在编辑器中打开了一个场景
• 请先尝试保存场景

节点路径不工作

• 使用从场景根开始的绝对路径（例如。， /root/Player)
• 或者使用编辑后的场景根的相对路径
• 检查节点名称是否准确（区分大小写）

屏幕截图返回错误

• 确保编辑器中有一个可见的视口
• 尝试在2D和3D编辑器视图之间切换

发展

添加新工具

1. 在中添加工具架构 mcp_protocol.gd → _handle_tools_list()
2. 在中添加工具处理程序 mcp_protocol.gd → _handle_tools_call()
3. 在以下相应模块中实现工具功能 tools/

测试

通过以下方式手动测试插件：

1. 在测试项目中启用插件
2. 使用curl或Postman发送请求
3. 连接像Claude Desktop这样的MCP客户端

卷曲测试示例：

curl -X POST http://localhost:8765 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {},
    "id": 1
  }'

需求

• Godot引擎4.0或更高版本
• 支持2D和3D项目

许可证

此插件按原样提供，用于Godot引擎项目。

贡献

欢迎投稿！请在GitHub存储库上提交问题和拉取请求。

致谢

• 为Godot引擎构建
• 实现模型上下文协议（MCP）规范
• 受人工智能辅助游戏开发需求的启发