使用说明
Godot MCP
通过模型上下文协议从Claude Code（或任何MCP客户端）控制Godot 4编辑器。
Godot MCP 是AI助手和Godot 4引擎之间的桥梁。它公开了18个MCP工具+3个编辑器端端点，让您无需离开终端即可检查场景、创建节点、修改属性、捕获屏幕截图、调试脚本和管理项目文件。
建筑
┌─────────────┐ stdio ┌─────────────────┐ HTTP ┌──────────────────┐
│ MCP Client │◄──────────────────►│ godot-mcp │◄──────────────►│ Godot 4 Editor │
│ (Claude Code)│ │ (Python server) │ localhost:6789 │ (Editor Plugin) │
└─────────────┘ └─────────────────┘ └──────────────────┘
该系统有两个组成部分：
- MCP 服务器 （Python）--通过stdio接收工具调用，并将其转换为HTTP请求
- 编辑器插件 （GDScript）-在Godot4内部运行，在上公开HTTP API
127.0.0.1:6789
安装
1.安装Python包
cd godot-mcp
pip install -e .
2.安装Godot插件
将插件文件夹复制到Godot项目中：
cp -r godot_plugin/addons/godot_mcp /path/to/your/godot-project/addons/
然后在戈多： 项目→ 项目设置→ 插件→ 启用“Godot MCP”
3.配置克劳德代码
添加到您的Claude Code MCP设置中(~/.claude.json 或项目配置）：
{
"mcpServers": {
"godot-mcp": {
"command": "godot-mcp",
"type": "stdio"
}
}
}
可用工具
| 工具 | 说明 |
|---|---|
get_editor_state |
获取当前编辑器状态（打开的场景、选定的节点） |
get_scene_tree |
获取完整的场景树层次结构 |
get_node_properties |
获取特定节点的所有属性 |
set_node_property |
实时修改节点属性 |
create_node |
在场景树中创建一个新节点（任何Godot类） |
delete_node |
从场景树中删除节点 |
save_scene |
将当前场景保存到磁盘 |
run_scene |
运行当前或特定场景 |
stop_scene |
停止跑步场景 |
execute_script |
在编辑器上下文中执行GDScript代码 |
get_project_files |
列出具有glob模式过滤的项目文件 |
read_script |
读取GDScript文件的内容 |
write_script |
编写或修改GDScript文件 |
get_viewport_screenshot |
将编辑器视口捕获为base64 PNG格式 |
get_logs |
从Godot控制台获取最近的日志和错误 |
search_assets |
搜索Godot资源库 |
download_asset |
从资产库下载并安装资产 |
preview_asset |
以base64 PNG格式预览项目中的图像文件 |
编辑器端端点（GDScript插件）
这些端点可以直接在Godot HTTP服务器上使用，并且可以通过MCP工具在内部访问：
| 端点 | 描述 |
|---|---|
GET /editor/errors |
从编辑器错误缓冲区获取经过筛选的错误消息 |
POST /script/check |
验证GDScript语法而不执行它 |
GET /editor/debugger |
通过MCPDebugCapture获取运行时调试器消息 |
用法示例
一旦启用了Godot插件并配置了Claude Code，您就可以自然地与Godot项目交互：
You: "Show me the scene tree of the current scene"
Claude: [calls get_scene_tree] → returns the full node hierarchy
You: "Move the Player node to position (100, 200)"
Claude: [calls set_node_property("Player", "position", "Vector2(100, 200)")]
You: "Run the game and check if it works"
Claude: [calls run_scene] → launches the scene in Godot
You: "Create a new script that makes the player jump"
Claude: [calls write_script("res://scripts/player.gd", "...GDScript code...")]
You: "Check my script for syntax errors"
Claude: [calls execute_script via /script/check] → returns compilation errors if any
You: "Show me the recent errors"
Claude: [calls get_logs(level="error")] → returns filtered error messages
需求
- 戈多4.x 启用编辑器插件
- Python 3.10+
- 依赖关系：
mcp >= 1.0.0,httpx >= 0.27.0
项目结构
godot-mcp/
├── src/godot_mcp/
│ ├── __init__.py
│ └── server.py # MCP server (18 tools)
├── godot_plugin/addons/godot_mcp/
│ ├── plugin.cfg # Plugin metadata
│ ├── plugin.gd # Plugin entry point
│ └── godot_mcp_server.gd # HTTP server + error tracking + debug capture
└── pyproject.toml
许可证
麻省理工学院
