Skip to main content
Glama
deenesjakoruzh
wvfp

Gear

by wvfp
OverviewSchemaRelated ServersScoreDiscussions
Local

这是什么

Gear MCP Server 是一个 C++ GDExtension，在 Godot 编辑器进程内部 运行一个 MCP 服务器。不需要单独的守护进程，不需要折腾 socket —— 加载插件，打开编辑器，你的 AI 客户端就能通过 109 个类型良好的工具来读取、写入、重构项目。

本仓库发布两个产物：

产物

类型

路径

gear-mcp-server

GDExtension 动态库

project/addons/gear_mcp/bin/

gear-mcp-proxy

npm 包

proxy/

Related MCP server: godot-mcp-pilot

架构

  • 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 个工具）

域

数量

亮点

file

3

读、写、列举

project

5

设置、autoload（只读）、项目信息、版本

classdb

3

类、属性、方法的内省

import

5

重新导入、列举、设置、预设

场景与世界（18 个工具）

域

数量

亮点

scene

10

打开、保存、实例化、运行时挂载，外加 7 个高级操作（节点、属性、信号、组）

runtime

4

生成场景实例、设置/读取变量、等待信号

tilemap

2

设置/读取格子

navigation

2

地图区域、代理路径

代码与调试（13 个工具）

域

数量

亮点

script

3

读、写、挂载

debug

10

LSP：诊断、悬停、补全、定义 · DAP：断点、单步、继续、变量、栈、求值

编辑器与插件（19 个工具）

域

数量

亮点

editor

6

选择、撤销/重做、截图、播放、停止、重载

autoload

4

添加、删除、列举、注册

plugin

3

启用、禁用、列举

signal

3

列举、连接、发射

theme

3

创建、应用、列举

媒体（14 个工具）

域

数量

亮点

resource

5

加载、保存、列举、检查、创建

audio

4

总线、流播放器、生成音调、监听器

animation

5

创建轨道、添加关键帧、设置值、播放、停止

输入与标识（3 个工具）

域

数量

亮点

input

1

动作映射

uid

2

生成、解析

构建与导出（2 个工具）

域

数量

亮点

export

2

预设、运行（跨平台进程生成）

AI 工作流（24 个工具）

域

数量

亮点

intent

9

快照、决策日志、工作步骤、追踪、录制开关、汇总、交接

meta

2

工具目录、schema 查询

assets

3

CC0 素材下载：Poly Haven、AmbientCG、Kenney

testing

6

注入输入、截图、无头运行、日志断言

dx

4

项目健康检查、lint、文件索引、符号索引

资源与提示词

资源（5 个）

URI

描述

godot://editor/context

当前选择、正在编辑的场景、帧率

godot://project/info

项目名、版本、autoload、设置摘要

godot://scene/{path}

实时场景树

godot://script/{path}

脚本文本 + 解析诊断

godot://resource/{path}

资源文本转储（.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 自动拉取，无需手动安装。

库

版本

用途

godot-cpp

git submodule

GDExtension C++ 绑定

nlohmann/json

3.11.3

JSON 解析/序列化（唯一的 JSON 库）

cpp-httplib

0.18.7

CC0 资产下载的 HTTP 客户端

inih

r58

project.godot INI 解析器

ws2_32

—

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。

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wvfp/gear-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server