Gear

Gear

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.

Category
Visit Server

README

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

Gear

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

MCP Server for Godot 4

Gear Logo

Made with Godot npm

b7c8d39c507e0f317f89a940ce057846b7028fe8

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

架构概览

Architecture

快速开始 (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 查询、运行时检查、断点调试

工具一览

Tools Overview

Compact 模式工作原理

Compact Mode

适用场景

  • ✅ 独立开发者使用 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

功能一览

快速开始流程

Quickstart

场景编辑

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

脚本工作流

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

运行时调试

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

输入与截图

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

资产管理

  • 搜索 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。

致谢

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured