AI导哈

Godot游戏开发MCP服务器

一个基于模型上下文协议（MCP）的服务器，使Claude能够以编程方式创建、操作和测试Godot游戏（2D和3D）。

  • by DARK-Shadw
  • GDScript
  • 本地部署
  • 更新于
在 GitHub 查看 DARK-Shadw/Godot-MCP

使用说明

Godot MCP服务器

一个模型上下文协议（MCP）服务器，使Claude能够以编程方式创建、操纵和测试Godot游戏（2D和3D）。

概述

该项目为AI驱动的Godot游戏开发提供了一个完整的解决方案：

  • MCP服务器：基于Python的MCP服务器，提供游戏创建工具
  • Godot网桥服务器：GDScript HTTP服务器在无头Godot中运行
  • 完整游戏创建：创建场景、节点、脚本、CSG形状等
  • 测试与捕获：运行游戏、模拟输入、截图

建筑

Claude ←→ MCP Server ←→ Godot Bridge Server ←→ Godot Engine (Headless)
         (JSON-RPC)      (HTTP/JSON)           (GDScript API)

特性

场景管理

  • 创建新的2D/3D场景
  • 加载并保存场景
  • 获取场景树结构

节点操作

  • 创建任何Godot节点类型
  • 设置属性（位置、比例、旋转等）
  • 在层次结构中移动节点
  • 删除节点
  • 查询节点信息

脚本管理

  • 从模板创建GDScript文件
  • 将脚本附加到节点
  • 更新脚本内容
  • 多个模板（节点、CharacterBody2D/3D、刚体2D/3D等）

CSG工具（3D）

  • 创建CSG形状（长方体、球体、圆柱体、圆环体等）
  • 设置CSG操作（并集、交集、减法）
  • 以编程方式构建复杂的三维几何体

游戏执行

  • 在播放模式下运行场景
  • 停止运行场景
  • 模拟键盘/鼠标/控制器输入
  • 测试游戏行为

捕获与分析

  • 截图
  • 获取base64编码的图像以获得视觉反馈
  • 视频捕获（帧序列）

安装

先决条件

  1. Godot引擎4.x -下载自https://godotengine.org/
  2. Python 3.8+
  3. 点 （Python包管理器）

设置

  1. 克隆存储库 （如果你正在读这篇文章，已经完成了！）

  2. 安装Python依赖项:

    cd mcp-server
pip install -r requirements.txt

  3. 构建Godot （可选-仅当您想修改引擎时）：

    cd godot
scons platform=linuxbsd target=editor

    或者下载预构建的Godot编辑器二进制文件。

用法

步骤1：启动Godot网桥服务器

# Navigate to godot-bridge directory
cd godot-bridge

# Run with Godot (headless mode recommended for production)
godot --headless --path . bridge_server.tscn

# Or with display for debugging:
godot --path . bridge_server.tscn

网桥服务器将启动 http://127.0.0.1:8765

步骤2：启动MCP服务器

cd mcp-server
python server.py

第三步：连接克劳德

将MCP服务器添加到您的Claude配置中：

适用于克劳德桌面 -添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "godot": {
      "command": "python",
      "args": ["/path/to/Godot-MCP/mcp-server/server.py"]
    }
  }
}

克劳德代码 -在项目目录中运行时，将自动检测MCP服务器。

第四步：开始制作游戏！

现在，您可以让Claude创建游戏：

“创建一个简单的2D平台游戏，玩家角色可以移动和跳跃”

“使用一些CSG形状构建3D场景，以创建一个简单的房间”

“为玩家创建一个处理WASD动作的脚本”

示例工作流

创建一个简单的2D游戏

# Claude will execute these tools:

1. create_scene(scene_name="Main", scene_type="2D")
2. create_node(node_type="CharacterBody2D", node_name="Player")
3. create_node(node_type="Sprite2D", node_name="PlayerSprite", parent_path="Player")
4. create_script(script_path="res://scripts/player.gd", template="characterbody2d")
5. attach_script(node_path="Player", script_path="res://scripts/player.gd")
6. save_scene(scene_path="res://scenes/main.tscn")
7. run_scene()
8. capture_screenshot()

使用CSG创建3D房间

# Claude will execute these tools:

1. create_scene(scene_name="Room", scene_type="3D")
2. create_csg_shape(shape_type="box", properties={"size": {"x": 10, "y": 5, "z": 10}, "name": "Floor"})
3. create_csg_shape(shape_type="box", properties={"size": {"x": 10, "y": 5, "z": 0.5}, "name": "Wall"})
4. set_node_transform(node_path="Wall", position={"x": 0, "y": 2.5, "z": -5})
5. create_node(node_type="Camera3D", node_name="Camera")
6. set_node_transform(node_path="Camera", position={"x": 0, "y": 2, "z": 5})
7. save_scene(scene_path="res://scenes/room.tscn")

可用工具

场景工具

  • create_scene -创建新场景
  • load_scene -加载现有场景
  • save_scene -将场景保存到文件
  • get_scene_tree -获取场景层次结构

节点工具

  • create_node -创建任何类型的节点
  • delete_node -删除节点
  • set_node_property -设置任何节点属性
  • get_node_property -获取房产价值
  • move_node -将节点移动到新父节点
  • set_node_transform -设置位置/旋转/比例
  • list_available_nodes -列出所有可用节点类型

脚本工具

  • create_script -创建GDScript文件
  • attach_script -将脚本附加到节点
  • update_script -更新脚本内容

CSG工具

  • create_csg_shape -创建CSG形状
  • set_csg_operation -设置布尔运算

执行工具

  • run_scene -在播放模式下运行场景
  • stop_scene -停止跑步场景
  • send_input -模拟输入事件

捕获工具

  • capture_screenshot -截图

项目结构

Godot-MCP/
├── godot/                      # Godot engine source (cloned)
├── godot-bridge/               # Godot Bridge Server
│   ├── bridge_server.gd        # Main HTTP server
│   ├── bridge_server.tscn      # Main scene
│   ├── scene_manager.gd        # Scene management
│   ├── node_manager.gd         # Node manipulation
│   ├── script_manager.gd       # Script handling
│   ├── csg_manager.gd          # CSG operations
│   ├── game_executor.gd        # Game execution
│   ├── input_simulator.gd      # Input simulation
│   ├── capture_manager.gd      # Screenshots/video
│   └── project.godot           # Godot project file
├── mcp-server/                 # Python MCP Server
│   ├── server.py               # Main MCP server
│   └── requirements.txt        # Python dependencies
├── docs/                       # Documentation
│   └── ARCHITECTURE.md         # Architecture details
└── README.md                   # This file

API 参考

看 docs/ARCHITECTURE.md API的详细文档。

故障排除

Godot网桥服务器无法启动

  • 确保Godot 4.x已安装并位于您的PATH中
  • 检查端口8765是否未使用
  • 试着不跑步 --headless 查看错误消息

MCP服务器连接问题

  • 验证网桥服务器是否正在运行
  • 检查URL http://127.0.0.1:8765 可访问的
  • 查找防火墙或网络问题

Godot中的脚本错误

  • GDScript错误将在工具响应中返回
  • 检查脚本语法，确保它与节点类型匹配
  • 使用提供的模板作为起点

性能问题

  • 无头模式比渲染模式快得多
  • 加载大型场景可能需要时间
  • 截图需要渲染，渲染速度较慢

高级用法

自定义模板

您可以通过修改来创建自定义脚本模板 script_manager.gd

扩展网桥服务器

在中添加新端点 bridge_server.gd 以及相应的管理人员

视频捕获

视频当前保存为PNG序列。使用ffmpeg进行转换：

ffmpeg -framerate 30 -i frame_%05d.png -c:v libx264 output.mp4

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 提交拉取请求

许可证

本项目使用：

  • Godot引擎（MIT许可证）
  • MCP SDK（MIT许可证）
  • Python库（各种许可证）

请参阅各个组件的许可证。

鸣谢

  • 戈多引擎: https://godotengine.org/
  • 人类MCP: https://modelcontextprotocol.io/
  • 克劳德·艾: https://claude.ai/

未来的增强功能

  • []动画创作和编辑
  • []视觉着色器支持
  • []资产库集成
  • []多人游戏测试
  • []物理模拟控制
  • []人工智能导航/寻路
  • []性能分析
  • []WebSocket支持实时更新
  • []GDExtension支持
  • []多项目管理

支持

对于问题和疑问：

  • 在GitHub上打开一个问题
  • 查看中的文档 docs/
  • 查看示例工作流

与Claude和Godot一起开发游戏！ 🎮🤖

相关 MCP