About Gear
Gear is an MCP server in the Gaming category: an MCP server that enables AI assistants to directly run, inspect, modify, and debug Godot game development projects through 110+ tools covering scenes, scripts, resources, runtime debugging, and asset management.
Install
git clone https://github.com/wvfp/Gear-Godot-MCPThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Ask AI
Ask AI about Gear
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
🌐 选择语言: English | 한국어 | 简体中文 | 日本語 | Deutsch | Português
Gear
<<<<<<< HEAD
MCP Server for Godot 4
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 进行了二次开发，用于适配我的项目需求
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.