使用说明
Godot MCP
https://github.com/user-attachments/assets/3b52def9-4663-4804-bb32-c7511511a422
Godot MCP是一个模型上下文协议服务器，允许AI代理自动化 Godot 4游戏引擎——创建场景、运行项目、捕获渲染和发送 通过输入 模型上下文协议.
由...创建 杰森·马修·苏哈里.
特性
- 16个MCP工具 涵盖项目控制、场景编辑、渲染和交互
- 适用于任何MCP客户端 --Claude Code、Cursor、Windsurf、定制代理等。
- 戈多4.4+ 通过轻量级GDScript插件桥提供支持
- 仅限本地主机 使用令牌身份验证--无网络暴露
代理设置
如果您是AI代理（或正在配置AI代理），请参阅 SETUP_AGENT.md 有关所有环境变量、工具签名和故障排除的机器可读设置说明。
快速开始
1.安装
pip install pydantic
2.设置Godot桥插件
- 复制
godot_addon/mistral_mcp_bridge在您的Godot项目中addons/mistral_mcp_bridge. - 在中启用插件 项目>项目设置>插件.
- 在以下项目设置中设置桥接令牌
mistral_mcp/bridge_token.
3.运行MCP服务器
# Optional: point to your Godot executable
export GODOT_PATH="/path/to/godot"
export GODOT_BRIDGE_TOKEN="your-token"
python -m mcp_server
服务器通过stdio（JSON-RPC与Content-Length帧）进行通信。
4.连接您的MCP客户端
添加到客户的MCP配置中（例如。 claude_desktop_config.json):
{
"mcpServers": {
"godot": {
"command": "python",
"args": ["-m", "mcp_server"],
"cwd": "/path/to/this/repo"
}
}
}
工具
项目和过程控制
| 工具 | 说明 |
|---|---|
godot_get_version |
获取安装的Godot版本和可执行路径 |
godot_list_projects |
在目录下递归发现Godot项目 |
godot_launch_editor |
启动项目的Godot编辑器 |
godot_run_project |
在游戏模式下运行项目 |
godot_stop_execution |
停止正在运行的Godot进程 |
godot_get_debug_output |
使用基于光标的分页读取stdout/stderr |
godot_analyze_project |
场景、脚本、资源、自动加载的静态分析 |
场景编辑
| 工具 | 说明 |
|---|---|
scene_create |
使用指定的根节点类型创建新场景 |
scene_add_node |
将子节点添加到现有场景 |
scene_load_sprite |
将纹理加载到Sprite2D节点中 |
scene_export_mesh_library |
导出三维平铺集的网格库 |
scene_save |
保存场景或创建继承的变体 |
资源
| 工具 | 说明 |
|---|---|
uid_get |
获取资源的Godot UID |
uid_refresh_references |
更新整个项目中的UID引用 |
渲染与交互
| 工具 | 说明 |
|---|---|
render_capture |
编辑器或运行游戏的屏幕截图 |
render_interact |
发送鼠标点击、按键或相机控制 |
示例
// Create a 3D scene
{
"tool": "scene_create",
"arguments": {
"project_path": "C:/Projects/MyGame",
"scene_path": "scenes/level_01.tscn",
"root_node_type": "Node3D"
}
}
// Capture a screenshot of the running game
{
"tool": "render_capture",
"arguments": {
"project_path": "C:/Projects/MyGame",
"mode": "running",
"width": 1280,
"height": 720
}
}
// Click in the game window
{
"tool": "render_interact",
"arguments": {
"project_path": "C:/Projects/MyGame",
"mode": "mouse_click",
"payload": { "x": 640, "y": 360, "button": 1 }
}
}
建筑学
MCP Client <--stdio--> mcp_server (Python) <--HTTP--> Godot Bridge Addon (GDScript)
127.0.0.1:19110 + Bearer token
mcp_server/--Python MCP服务器处理工具调度和验证（Pydantic模式）godot_addon/mistral_mcp_bridge/--GDScript@tool插件在Godot编辑器中运行HTTP服务器
测试
# Unit tests
python -m pytest -q
# Integration tests (requires Godot 4.4+)
ENABLE_GODOT_INTEGRATION=1 GODOT_PATH="/path/to/godot" python -m pytest -q tests_integration
需求
- Python 3.11+
- 戈多4.4+
pydantic
许可证
看 许可证 了解详情。
