Gear

Gear 让 AI 助手可以直接运行、检查、修改和调试你的 Godot 项目。

快速开始 (3 分钟)

环境要求

• Godot 4.x
• Node.js 18+
• 支持 MCP 的客户端 (Claude Desktop, Cursor, Cline 等)

1) 启动 Gear

npx -y gear

或全局安装：

npm install -g gear-godot-mcp
gear

2) 配置 MCP 客户端

在 Claude Desktop 等客户端的配置文件中添加：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "gear"],
      "env": {
        "GODOT_PATH": "/path/to/godot"
      }
    }
  }
}

3) 试试这些指令

• "列出 /your/projects 目录下的所有 Godot 项目"
• "创建 scenes/Player.tscn，根节点用 CharacterBody2D"
• "运行项目，获取调试输出，然后修复错误"

为什么用 Gear

核心优势

适用场景

• ✅ 独立开发者使用 AI 加速开发
• ✅ 需要 AI 了解真实项目/运行时状态的团队
• ✅ 重度调试工作流 (断点、堆栈跟踪、运行时检查)

工具使用模式

工具暴露级别

Gear 有三种工具暴露模式：

compact 模式的动态工具组

在 compact 模式下，78 个额外工具被组织成 22 个动态工具组：

工具组使用方式

1. 自动激活 (推荐)

使用 tool.catalog 搜索相关工具，匹配的工具组会自动激活

2. 手动激活

使用 tool.groups 手动激活特定工具组 "激活 dap 工具组进行调试"

3. 停用

使用 tool.groups 重置已激活的组

安装方式

方式 A: npx (推荐)

npx -y gear

方式 B: 全局安装

npm install -g gear-godot-mcp
gear

方式 C: 源码安装

git clone https://github.com/HaD0Yun/Gear-godot-mcp.git
cd Gear-godot-mcp
npm install
npm run build
node build/index.js

功能一览

场景编辑

• 创建场景、添加/删除节点
• 修改节点属性
• 节点重新父化

脚本工作流

• 创建/修改脚本
• 分析脚本结构
• 符号重命名

运行时调试

• 检查运行时场景树
• 设置断点、单步执行
• 查看变量值

输入与截图

• 注入键盘/鼠标输入
• 截取游戏画面
• 视口捕获

资产管理

• 搜索 CC0 素材 (Poly Haven, AmbientCG, Kenney)
• 下载资源到项目

环境变量

常见问题

相关链接

• 架构文档
• 开发路线图
• 更新日志
• 贡献指南

许可证

MIT — 详见 LICENSE。

致谢

• 原始 MCP 服务器来自 Coding-Solo
• Gear 增强功能由 HaD0Yun 开发
• 项目可视化功能受 tomyud1/godot-mcp 启发