Godot MCP Unified - AI + Godot 架构

给未来的自己看的文档 - 在 Godot 中进行自然语言编程的完整配置

阅读英文版

全局架构

                    +------------------+
                    |   Claude Code    |
                    |    (VS Code)     |
                    +--------+---------+
                             |
                             v
+----------------+  +--------+---------+  +------------------+
| Claude Desktop |->|                  |<-| ollmcp (Ollama)  |
|   (Anthropic)  |  | godot-mcp-unified|  | qwen2.5-coder:7b |
+----------------+  |   (ce serveur)   |  +------------------+
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
              v                             v
     +--------+---------+          +--------+---------+
     |  Godot CLI       |          |  Plugin WebSocket|
     |  (--headless)    |          |  (addons/godot_  |
     |  Fallback mode   |          |   mcp/) Port 6505|
     +------------------+          +------------------+
              |                             |
              +-------------+---------------+
                            |
                            v
                   +--------+---------+
                   |  Godot Engine    |
                   |    4.5.1         |
                   +------------------+

与 Godot 通信

服务器会自动检测插件是否连接并使用最佳模式。

该服务器的功能

在 Godot 中通过自然语言完成一切（83 个工具 + 20 个资源 + 20 个提示词）：

安装（已完成）

已安装的先决条件

• Node.js (用于 MCP 服务器)

• Godot 4.5.1: C:\Dev\Godot_v4.5.1-stable_win64.exe\Godot_v4.5.1-stable_win64_console.exe

• uv (现代 Python 管理器)

• ollmcp (Ollama <-> MCP 桥接器)

本服务器

cd C:\Dev\godot-mcp-unified
npm install
npm run build

配置

Claude Desktop (C:\Users\pierr\AppData\Roaming\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

VS Code / Claude Code (Godot 项目中的 .vscode/mcp.json)

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

Ollama (通过 ollmcp)

# Lancer le bridge
ollmcp --model qwen2.5-coder:7b C:\Dev\godot-mcp-unified\build\index.js

# Ou via ollama-gateway (port 3010)

可用的 Ollama 模型

注意： -chess 模型并非用于下棋，而是作为使用 FFE 系统提示词开发 chess-app 的定制助手。

API 参考 (83 个工具 + 20 个资源 + 20 个提示词)

统计信息

Primitives MCP:
  Tools:     83/83   ████████████████████ 100%
  Resources: 20/20   ████████████████████ 100%
  Prompts:   20/20   ████████████████████ 100%

Qualite:
  Tests:    3170+    ████████████████████ 100% pass (69 suites)
  Coverage:  85%     █████████████████░░░  85%

Bridge Plugin:
  Avec bridge:  47 outils (utilisent WebSocket si plugin actif)
  Sans bridge:  35 outils (CLI/file I/O uniquement)

项目管理 (14 个工具)

• launch_editor - 打开 Godot 编辑器

• run_project - 运行项目

• stop_project - 停止项目

• list_projects - 列出文件夹中的项目

• get_project_info - 获取项目信息

• get_godot_version - 获取 Godot 版本

• get_project_settings - 读取项目设置

• set_project_setting - 修改设置

• manage_input_actions - 管理输入动作

• manage_autoloads - 管理自动加载

• validate_project - 验证项目结构

• convert_project - 将 Godot 3 项目转换为 4

• validate_conversion - 验证转换

• generate_docs - 生成 GDScript 文档

场景管理 (15 个工具)

• create_scene - 创建新场景

• add_node - 添加节点

• edit_node - 修改节点属性

• remove_node - 删除节点

• rename_node - 重命名节点

• move_node - 移动节点 (重父级)

• duplicate_node - 复制节点

• load_sprite - 加载纹理

• save_scene - 保存场景

• instance_scene - 实例化场景

• list_scenes - 列出场景

• get_node_tree - 获取场景树

• connect_signal - 连接信号

• manage_groups - 管理节点组

• export_mesh_library - 导出为 MeshLibrary

GDScript 脚本 (7 个工具)

• list_scripts - 列出项目中所有 .gd 文件

• read_script - 读取脚本内容

• write_script - 创建/修改脚本

• delete_script - 删除脚本

• attach_script - 将脚本附加到节点

• detach_script - 从节点分离脚本

• get_script_errors - 编译错误

动画 (7 个工具)

• create_animation_player - 创建 AnimationPlayer

• add_animation - 添加动画

• add_animation_track - 添加轨道 (值、位置、旋转等)

• set_keyframe - 设置带有过渡/缓动的关键帧

• create_animation_tree - 创建 AnimationTree

• setup_state_machine - 配置状态机

• blend_animations - 配置动画混合

物理 (3 个工具)

• create_collision_shape - 创建 CollisionShape2D/3D

• setup_rigidbody - 配置刚体 (质量、重力)

• configure_physics_layers - 命名 2D/3D 物理层

TileMap (5 个工具)

• create_tileset - 创建带有瓦片大小的 TileSet

• create_tilemap_layer - 创建 TileMapLayer

• set_tile - 放置瓦片

• paint_tiles - 批量绘制瓦片

• import_ldtk_level - 导入 LDtk 关卡

音频 (3 个工具)

• create_audio_bus - 创建音频总线

• setup_audio_player - 配置 AudioStreamPlayer

• add_audio_effect - 添加效果 (混响、延迟、均衡器)

着色器 (2 个工具)

• create_shader - 创建 .gdshader 文件

• create_shader_material - 创建 ShaderMaterial

导航 (2 个工具)

• create_navigation_region - 创建 NavigationRegion2D/3D

• bake_navigation_mesh - 烘焙导航网格

粒子 (2 个工具)

• create_gpu_particles - 创建 GPUParticles2D/3D

• create_particle_material - 创建 ParticleProcessMaterial

UI (2 个工具)

• create_ui_container - 创建容器 (VBox, HBox, Grid 等)

• create_control - 创建控件 (Button, Label 等)

灯光 (3 个工具)

• create_light - 创建 Light2D/3D (Directional, Omni, Spot)

• setup_environment - 配置环境 (雾、辉光、SSAO)

• setup_lightmapper - 配置 LightmapGI 和烘焙

资源 (3 个工具)

• list_assets - 列出资源 (图像、音频、模型)

• import_asset - 导入外部文件

• reimport_assets - 强制重新导入

导出 (3 个工具)

• export_project - 导出项目

• export_pack - 仅导出 PCK

• list_export_presets - 列出导出预设

批处理操作 (1 个工具)

• batch_operations - 按顺序执行多个 MCP 工具

调试 (5 个工具)

• get_debug_output - 获取控制台输出

• start_debug_stream - 启动调试 WebSocket 服务器

• stop_debug_stream - 停止 WebSocket 服务器

• get_debug_stream_status - 服务器状态

• take_screenshot - 截屏

UID (Godot 4.4+) (2 个工具)

• get_uid - 获取文件 UID

• update_project_uids - 更新引用

系统 (2 个工具)

• system_health - 系统健康检查

• get_godot_version - Godot 版本

使用示例

创建玩家角色

"Cree une scene Player.tscn avec un CharacterBody2D comme root,
ajoute un Sprite2D nomme 'Sprite' et un CollisionShape2D nomme 'Collision'"

调试项目

"Lance mon projet Godot et montre-moi les erreurs dans la console"

修改现有场景

"Dans la scene Player.tscn, change la position du Sprite a (100, 50)
et sa scale a 2x"

Godot 项目结构

C:\Dev\
├── jdvlh-godot-client\     <- Projet principal (pas de remote git configure!)
│   ├── project.godot
│   ├── .vscode\mcp.json    <- Config MCP pour ce projet
│   └── addons\godot_mcp\   <- Plugin MCP copie
│
├── jdvlh-godot\            <- Projet vide (a garder pour tests)
│
└── GodotDynamicDialog\     <- Fork de dynamic-dialog

代码来源

本服务器整合了 3 个开源项目的功能：

注意： GDAI MCP 存在但需要付费 ($19)。

机器规格

• CPU: Ryzen 5 5600H

• RAM: 16 GB

• GPU: AMD Radeon (集成) - 无 CUDA

• 最佳量化: Q4_K_M (质量/性能的最佳平衡点)

故障排除

服务器无法启动

cd C:\Dev\godot-mcp-unified
npm run build

找不到 Godot

检查 GODOT_PATH 是否指向正确的执行文件（控制台版本以便查看日志）。

Claude Desktop 看不到工具

修改配置后重启 Claude Desktop。

有用命令

# Rebuild le serveur
cd C:\Dev\godot-mcp-unified && npm run build

# Tester avec l'inspecteur MCP
npm run inspector

# Lister les modeles Ollama
ollama list

# Supprimer un modele Ollama
ollama rm nom_modele

TODO

• [ ] 为 jdvlh-godot-client 配置 git remote

• [ ] 清理冗余的 Ollama 模型 (qwen2.5, gemma2, llama3.2, deepseek-coder-v2)

• [ ] 使用新项目测试完整集成

最后更新: 2026年2月11日 godot-mcp-unified v0.9.0 - 83 个工具 + 20 个资源 + 20 个提示词 覆盖率: 85% | 测试: 3170+ (69 个套件) | 符合 ISO 25010/29119/5055/27001 标准