🌐 选择语言: English | 한국어 | 简体中文 | 日本語 | Deutsch | Português

Gear

<<<<<<< HEAD Made with Godot npm

MCP Server for Godot 4

Made with Godot npm

b7c8d39c507e0f317f89a940ce057846b7028fe8

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

核心优势

特性	说明
实时反馈	运行游戏、检查日志、即时修复
110+ 工具	覆盖场景/脚本/资源/运行时/LSP/调试/输入/资产
Token 高效	默认仅暴露 33 个核心工具，按需激活
动态工具组	搜索工具时自动激活相关工具组
深度集成	ClassDB 查询、运行时检查、断点调试

工具一览

Compact 模式工作原理

适用场景

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

---

工具使用模式

工具暴露级别

Gear 有三种工具暴露模式：

模式	工具数量	说明
compact (默认)	33 核心 + 78 按需激活	Token 高效，按需加载
full	110+	全部暴露
legacy	110+	与 full 相同

compact 模式的动态工具组

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

工具组	工具数	说明
scene_advanced	3	节点复制、重新父化、加载精灵
runtime	4	运行时场景检查、属性修改
dap	6	断点、单步执行、堆栈跟踪
lsp	3	代码补全、悬停、符号列表
testing	6	截图、输入注入
animation	5	动画、轨道、状态机
resource	4	材质、着色器、资源创建
...	...	还有更多

工具组使用方式

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/wvfp/Gear-godot-mcp.git
cd Gear-godot-mcp
npm install
npm run build
node build/index.js

---

功能一览

快速开始流程

场景编辑

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

脚本工作流

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

运行时调试

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

输入与截图

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

资产管理

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

---

环境变量

变量	用途	默认值
GEAR_TOOL_PROFILE	工具暴露模式	compact
GODOT_PATH	Godot 可执行文件路径	自动检测
GODOT_BRIDGE_PORT	Bridge 服务端口	6505
GEAR_TOOLS_PAGE_SIZE	工具列表分页大小	33
DEBUG	调试日志	false

---

常见问题

问题	解决方案
Godot 未找到	设置 GODOT_PATH 环境变量
工具列表为空	重启 MCP 客户端
项目路径无效	确认 project.godot 文件存在
运行时工具不工作	安装并启用 runtime addon 插件
找不到需要的工具	使用 tool.catalog 搜索激活相关工具组

---

相关链接

• 架构文档
• 更新日志
• 贡献指南

许可证

MIT — 详见 LICENSE。

致谢

• 基于 HaD0Yun 的 Gopeak-godot-mcp 进行了二次开发，用于适配我的项目需求