Gear
这是什么
Gear MCP Server 是一个 C++ GDExtension,在 Godot 编辑器进程内部 运行一个 MCP 服务器。不需要单独的守护进程,不需要折腾 socket —— 加载插件,打开编辑器,你的 AI 客户端就能通过 109 个类型良好的工具来读取、写入、重构项目。
本仓库发布两个产物:
产物 | 类型 | 路径 |
| GDExtension 动态库 |
|
| npm 包 |
|
Related MCP server: Godot MCP Enhanced
架构
GDExtension 在
127.0.0.1:8510上开启一个TCPServer(可通过GEAR_PORT覆盖)。每个客户端连接由独立线程处理;JSON-RPC 2.0 消息以
\n分隔(没有Content-Length头)。工具 handler 在线程安全的
ToolRegistry中注册。需要访问 Godot 对象的 handler 标记为main_thread=true,并通过MainThreadQueue分发到编辑器的_process循环。gear-mcp-proxy是一个约 50 行的 Node.js 桥接,将 MCP 客户端的 stdio JSON-RPC 桥接到 TCP socket。以npx -y gear-mcp-proxy运行(本地路径:cd proxy && node index.js)。
快速上手
1. 编译 GDExtension
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug输出到 project/addons/gear_mcp/bin/。文件名格式:
libgear_mcp_server.{platform}.{variant}.{arch}.{ext} —— 例如 Windows 上为
libgear_mcp_server.windows.template_debug.x86_64.dll。
GODOTCPP_TARGET(默认 template_debug)控制后缀。.gdextension 文件
已列出全部六种变体(debug/release × windows/linux/macos)。
2. 在 Godot 4.4+ 中打开项目
打开 project/ 目录。GDExtension 会自动加载并启动 TCP 服务器。
3. 运行代理并调用工具
# 终端 1
cd proxy && node index.js
# 终端 2
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node proxy/index.js代理最多重试 60 秒等待编辑器启动。可通过 GEAR_HOST / GEAR_PORT 覆盖。
4. 接入 MCP 客户端
{
"mcpServers": {
"gear": {
"command": "npx",
"args": ["-y", "gear-mcp-proxy"]
}
}
}工具(109 个,跨 26 个域)
文件与项目(16 个工具)
域 | 数量 | 亮点 |
| 3 | 读、写、列举 |
| 5 | 设置、autoload(只读)、项目信息、版本 |
| 3 | 类、属性、方法的内省 |
| 5 | 重新导入、列举、设置、预设 |
场景与世界(18 个工具)
域 | 数量 | 亮点 |
| 10 | 打开、保存、实例化、运行时挂载,外加 7 个高级操作(节点、属性、信号、组) |
| 4 | 生成场景实例、设置/读取变量、等待信号 |
| 2 | 设置/读取格子 |
| 2 | 地图区域、代理路径 |
代码与调试(13 个工具)
域 | 数量 | 亮点 |
| 3 | 读、写、挂载 |
| 10 | LSP:诊断、悬停、补全、定义 · DAP:断点、单步、继续、变量、栈、求值 |
编辑器与插件(19 个工具)
域 | 数量 | 亮点 |
| 6 | 选择、撤销/重做、截图、播放、停止、重载 |
| 4 | 添加、删除、列举、注册 |
| 3 | 启用、禁用、列举 |
| 3 | 列举、连接、发射 |
| 3 | 创建、应用、列举 |
媒体(14 个工具)
域 | 数量 | 亮点 |
| 5 | 加载、保存、列举、检查、创建 |
| 4 | 总线、流播放器、生成音调、监听器 |
| 5 | 创建轨道、添加关键帧、设置值、播放、停止 |
输入与标识(3 个工具)
域 | 数量 | 亮点 |
| 1 | 动作映射 |
| 2 | 生成、解析 |
构建与导出(2 个工具)
域 | 数量 | 亮点 |
| 2 | 预设、运行(跨平台进程生成) |
AI 工作流(24 个工具)
域 | 数量 | 亮点 |
| 9 | 快照、决策日志、工作步骤、追踪、录制开关、汇总、交接 |
| 2 | 工具目录、schema 查询 |
| 3 | CC0 素材下载:Poly Haven、AmbientCG、Kenney |
| 6 | 注入输入、截图、无头运行、日志断言 |
| 4 | 项目健康检查、lint、文件索引、符号索引 |
资源与提示词
资源(5 个)
URI | 描述 |
| 当前选择、正在编辑的场景、帧率 |
| 项目名、版本、autoload、设置摘要 |
| 实时场景树 |
| 脚本文本 + 解析诊断 |
| 资源文本转储(.tres / .res 元数据) |
资源 URI 使用模板前缀 —— 服务器会把 godot://script/res://player.gd 解析到
匹配的 handler。
提示词(2 个)
gear:save-intent-snapshot—— 生成结构化的意图快照gear:summarize-session—— 从意图状态汇总当前编辑器会话
项目结构
gear-mcp-server/
├── CMakeLists.txt # 顶层构建(godot-cpp、nlohmann/json、cpp-httplib、inih,通过 FetchContent)
├── project/ # Godot 项目(自动加载 GDExtension)
│ └── addons/gear_mcp/
│ ├── gear_mcp.gdextension
│ └── plugin.cfg
├── proxy/ # Node.js stdio↔TCP 桥接
│ ├── index.js
│ └── package.json
├── contrib/
│ └── agent-skill/ # AI 代理 skill(可拷贝到 IDE 的 skills/ 目录)
├── src/
│ ├── register_types.cpp # GDExtension 入口(仅编辑器模式)
│ ├── gear_main_thread_node.* # EditorProcessFrame 桥接
│ ├── godot_api/ # 30+ GDExtension C API 函数指针
│ ├── server/ # TCPServer、MCPMethods、ToolRegistry、MainThreadQueue
│ ├── shared/ # type_codec、path_utils、config_parser、json_rpc_client、logger
│ └── tools/ # 26 个域,每域一个目录
└── tests/ # Node.js E2E 测试套件(e2e_test、e2e_live_editor、e2e_phase4)线程模型
标记为
main_thread=true的 handler 在编辑器的_process中通过MainThreadQueue::invoke_on_main运行,阻塞 TCP 线程直到编辑器帧完成它们。标记为
main_thread=false的 handler(文件 I/O、INI 解析、资产下载)直接在 TCP 线程上执行。意图状态文件在每次修改时原子重写;访问由递归互斥锁保护。
依赖
通过 CMake FetchContent 自动拉取,无需手动安装。
库 | 版本 | 用途 |
| git submodule | GDExtension C++ 绑定 |
| 3.11.3 | JSON 解析/序列化(唯一的 JSON 库) |
| 0.18.7 | CC0 资产下载的 HTTP 客户端 |
| r58 |
|
| — | Windows 上的 TCP socket |
给 AI 代理的使用指南
contrib/agent-skill/SKILL.md 是一份 Trae / Claude / Cursor skill,
教 AI 代理怎么用 MCP 工具驱动本项目——包括标准工作流、截图管道、
7 个常见坑和 editor 卡住时的恢复步骤。把 contrib/agent-skill/
整目录复制到 IDE 的 skill 目录(如 ~/.trae-cn/builtin/global/skills/)即可加载。
许可证
MIT —— 详见 LICENSE。
Available Tools
33 toolsclass-infoA
[compact alias of query_class_info] Get detailed information about a specific Godot class: methods, properties, signals, enums. Use to discover available properties before calling add_node/create_resource/set_node_properties, or to find methods before call_runtime_method.
Inputs: projectPath (required), className (required), includeInherited.
class-queryA
[compact alias of query_classes] Query available Godot classes from ClassDB with filtering. Use to discover node types, resource types, or any class before using add_node/create_resource. Categories: node, node2d, node3d, control, resource, physics, physics2d, audio, visual, animation.
Inputs: projectPath (required), filter, category, instantiableOnly.
dap-outputB
[compact alias of dap_get_output] Get captured Godot DAP console output lines
Inputs: no named parameters.
editor-debug-outputA
[compact alias of get_debug_output] Retrieves console output and errors from the currently running Godot project. Use after run_project to check logs, errors, and print statements. Returns empty if no project is running.
Inputs: reason (required).
editor-launchA
[compact alias of launch_editor] Opens the Godot editor GUI for a project. Use when visual inspection or manual editing of scenes/scripts is needed. Opens a new window on the host system. Requires: project directory with project.godot file.
Inputs: projectPath (required).
editor-runA
[compact alias of run_project] Launches a Godot project in a new window and captures output. Use to test gameplay or verify script behavior. Runs until stop_project is called. Use get_debug_output to retrieve logs.
Inputs: projectPath (required), scene.
editor-statusA
[compact alias of get_editor_status] Returns the connection status of the Godot Editor Plugin bridge. Use to check if the editor is connected before using scene/resource tools that require the editor plugin.
Inputs: no named parameters.
editor-stopA
[compact alias of stop_project] Terminates the currently running Godot project process. Use to stop a project started with run_project. No effect if no project is running.
Inputs: reason (required).
editor-versionA
[compact alias of get_godot_version] Returns the installed Godot engine version string. Use to check compatibility (e.g., Godot 4.4+ features like UID). Returns version like "4.3.stable" or "4.4.dev".
Inputs: reason (required).
export-presetsA
[compact alias of list_export_presets] Lists all export presets defined in export_presets.cfg. Use before export_project to see available targets (Windows, Linux, Android, etc.).
Inputs: projectPath (required), includeTemplateStatus.
export-runA
[compact alias of export_project] Exports the project to a distributable format. Use to build final game executables. Requires export templates installed.
Inputs: projectPath (required), preset (required), outputPath (required), debug.
lsp-diagnosticsC
[compact alias of lsp_get_diagnostics] Get GDScript diagnostics from Godot Language Server for a script file.
Inputs: projectPath (required), scriptPath (required).
project-infoA
[compact alias of get_project_info] Returns metadata about a Godot project including name, version, main scene, autoloads, and directory structure. Use to understand project before modifying. Requires valid project.godot.
Inputs: projectPath (required).
project-listA
[compact alias of list_projects] Scans a directory for Godot projects (folders containing project.godot). Use to discover projects before using other tools. Returns array of {path, name}.
Inputs: directory (required), recursive.
project-searchA
[compact alias of search_project] Searches for text or regex patterns across project files. Use to find function usages, variable references, or TODOs. Returns file paths and line numbers.
Inputs: projectPath (required), query (required), fileTypes, regex, +2 more.
project-setting-getA
[compact alias of get_project_setting] Reads a value from project.godot settings. Use to check game name, window size, physics settings, etc.
Inputs: projectPath (required), setting (required).
project-setting-setA
[compact alias of set_project_setting] Writes a value to project.godot settings. Use to configure game name, window size, physics, etc.
Inputs: projectPath (required), setting (required), value (required).
resource-dependenciesA
[compact alias of get_dependencies] Analyzes resource dependencies and detects circular references. Use to understand what a scene/script depends on before refactoring.
Inputs: projectPath (required), resourcePath (required), depth, includeBuiltin.
runtime-statusA
[compact alias of get_runtime_status] Checks if a Godot game instance is running and connected for live debugging. Use before other runtime tools.
Inputs: projectPath (required).
scene-createA
[compact alias of create_scene] Creates a new Godot scene file (.tscn) with a specified root node type. Use to start building new game levels, UI screens, or reusable components. The scene is saved automatically after creation.
Inputs: projectPath (required), scenePath (required), rootNodeType.
scene-node-addA
[compact alias of add_node] Adds ANY node type to an existing scene. This is the universal node creation tool — replaces all specialized create_* node tools. Supports ALL ClassDB node types (Camera3D, DirectionalLight3D, AudioStreamPlayer, HTTPRequest, RayCast3D, etc.). Set any property via the properties parameter with type conversion support (Vector2, Vector3, Color, etc.). Use query_classes to discover available node types. Use query_class_info to discover available properties for a type.
Inputs: projectPath (required), scenePath (required), nodeType (required), nodeName (required), +2 more.
scene-node-deleteA
[compact alias of delete_node] Removes a node and all its children from a scene. Use to clean up unused nodes. Cannot delete root node. Scene is saved automatically unless saveScene=false.
Inputs: projectPath (required), scenePath (required), nodePath (required), saveScene.
scene-node-propertiesA
[compact alias of get_node_properties] Returns all properties of a specific node in a scene. Use to inspect current values before modifying. Returns property names, values, and types.
Inputs: projectPath (required), scenePath (required), nodePath (required), includeDefaults.
scene-nodesA
[compact alias of list_scene_nodes] Returns complete scene tree structure with all nodes, types, and hierarchy. Use to understand scene organization before modifying. Returns nested tree with node paths.
Inputs: projectPath (required), scenePath (required), depth, includeProperties.
scene-node-setA
[compact alias of set_node_properties] Sets multiple properties on a node in a scene. Prerequisite: scene and node must exist (use create_scene and add_node first). Use to modify position, scale, rotation, or any node-specific properties. Scene is saved automatically unless saveScene=false.
Inputs: projectPath (required), scenePath (required), nodePath (required), properties (required), +1 more.
scene-saveA
[compact alias of save_scene] Saves changes to a scene file or creates a variant at a new path. Most scene modification tools save automatically, but use this for explicit saves or creating variants.
Inputs: projectPath (required), scenePath (required), newPath.
script-createA
[compact alias of create_script] Creates a new GDScript (.gd) file with optional templates. Use to generate scripts for game logic. Templates: "singleton" (autoload), "state_machine" (FSM), "component" (modular), "resource" (custom Resource).
Inputs: projectPath (required), scriptPath (required), className, extends, +3 more.
script-infoA
[compact alias of get_script_info] Analyzes a GDScript and returns its structure: functions, variables, signals, class_name, extends. Use before modify_script to understand existing code.
Inputs: projectPath (required), scriptPath (required), includeInherited.
script-modifyA
[compact alias of modify_script] Adds functions, variables, or signals to an existing GDScript. Use to extend scripts without manual editing. Supports @export, @onready annotations and type hints.
Inputs: projectPath (required), scriptPath (required), modifications (required), reason.
signal-connectA
[compact alias of connect_signal] Creates a signal connection between nodes in a scene. Prerequisite: source and target nodes must exist. Use to wire up button clicks, collision events, custom signals. Saved to scene file.
Inputs: projectPath (required), scenePath (required), sourceNodePath (required), signalName (required), +3 more.
tool-catalogA
[compact alias of tool_catalog] Discover available tools including hidden legacy tools. Use query to search by capability keywords. Results include group categorization (core/dynamic). Matching dynamic groups are auto-activated and become available immediately. Core groups (always visible): core_meta, core_project, core_editor, core_scene, core_script, core_class, core_signal, core_resource, core_export, core_runtime, core_visualizer, core_diagnostics. Dynamic groups (on-demand): scene_advanced, uid, import_export, autoload, signal, runtime, resource, animation, plugin, input, tilemap, audio, navigation, theme_ui, asset_store, testing, dx_tools, intent_tracking, class_advanced, lsp, dap, version_gate.
Inputs: query, limit.
tool-groupsA
[compact alias of manage_tool_groups] Manage tool groups. Actions: list (show all core + dynamic groups), activate (enable a dynamic group), deactivate (disable a dynamic group), reset (disable all dynamic), status (show current state). Core groups (always visible, 33 tools): core_meta, core_project, core_editor, core_scene, core_script, core_class, core_signal, core_resource, core_export, core_runtime, core_visualizer, core_diagnostics. Dynamic groups (on-demand, 78 tools): scene_advanced, uid, import_export, autoload, signal, runtime, resource, animation, plugin, input, tilemap, audio, navigation, theme_ui, asset_store, testing, dx_tools, intent_tracking, class_advanced, lsp, dap, version_gate.
Inputs: action (required), group.
visualizer-mapA
[compact alias of map_project] Crawl the entire Godot project and build an interactive visual map of all scripts showing their structure (variables, functions, signals), connections (extends, preloads, signal connections), and descriptions. Opens an interactive browser-based visualization at localhost:6505.
Inputs: projectPath (required), root, include_addons.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Most tools have clearly distinct purposes, especially with descriptive aliases. However, the large number of tools (33) and some overlap between output-related tools (dap-output, editor-debug-output, lsp-diagnostics) could cause minor confusion, though descriptions clarify the sources.
All tool names follow a consistent lowercase-with-hyphens pattern (e.g., class-info, editor-run). No mixed conventions or irregular formats, making it predictable for an agent.
33 tools is above the typical well-scoped range (3-15). While the breadth of Godot development justifies many tools, the count is borderline high and may overwhelm agents, despite the management tools (tool-catalog, tool-groups).
The toolset covers core Godot workflows: project, scene, script, class, export, runtime, debugging, and diagnostics. Minor gaps exist (e.g., no explicit file delete or node rename), but essential CRUD and lifecycle operations are present.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that gives AI assistants direct control over Godot 4 game development projects. It enables launching the editor, running projects, creating and editing scenes, writing GDScript, and inspecting assets through natural language commands.444MIT
- AlicenseBqualityDmaintenanceAn enhanced MCP server for interacting with the Godot game engine, enabling AI assistants to launch the editor, run projects, manage scenes and nodes, and handle scripts.16MIT
- AlicenseCqualityCmaintenanceAn MCP server providing AI assistants with 149 tools to fully control the Godot game engine, including runtime code execution, scene manipulation, physics, audio, networking, animation, and more.10098 npm515MIT
- AlicenseBqualityDmaintenanceThis MCP server allows AI assistants to control the Godot editor and running games, enabling scene creation, script editing, input simulation, and gameplay testing through 174 tools.100443 npm1MIT