better-godot-mcp

已于 2026-09-13 归档 — 此仓库已停止维护。请改用 Godot 编辑器 + GDScript 命令行工具链，而非此 MCP 服务。现有安装仍可使用，但不会收到更新或支持。

Better Godot MCP

mcp-name: io.github.n24q02m/better-godot-mcp

面向 Godot Engine 的复合 MCP 服务，提供 17 个复合工具，用于 AI 辅助游戏开发。

n24q02m 的姊妹项目（点击展开）

| Project | 标语 | 标签 | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | Peer AI Agent 在共享文件夹中聊天——无需人工中转、无需编排器，工... | 工具 | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | 用于高效利用 token 进行代码审查的知识图谱——语义搜索和调用... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | 支持 `.driveignore` 过滤器的 Google Drive 双向同步——基于 rclone 引擎，提供 Windows 托盘 | 工具 | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | 面向 AI Agent 的 IMAP/SMTP 电子邮件——读取、发送、整理文件夹和管理附... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | 面向 Godot Engine 的复合 MCP 服务——提供 17 个复合工具，支持 AI 辅助游... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | 面向 AI Agent、以 Markdown 为先的 Notion——页面、数据库、区块和评论... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | 可直接替换的 python-semantic-release 分支，内置发布安全防护（过... | 工具 | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | 面向 AI Agent 的 Telegram——支持两种 bo...上的消息、聊天、媒体和联系人 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP 服务（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | 面向 n24q02m MCP 服务的 Claude Code 插件市场——安装网页搜索... | 市场 | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | 面向 AI Agent 的图像与视频理解和生成——支持 Gemini、Op... | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | 通过 batchexecute API 批量操作 Jules 任务的 Chrome 扩展——... | 工具 | | [mcp-core](https://github.com/n24q02m/mcp-core) | 用于构建 MCP 服务的共享基础组件——Streamable HTTP 传输、OAut... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | 支持混合搜索和嵌入式同步的持久化 AI 记忆。开放、免费、无... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | 通过 ONNX Runtime 和 GGUF 实现的轻量级 Qwen3 文本嵌入与重排序 | 库 | | [skret](https://github.com/n24q02m/skret) | 无需服务器的密钥管理。 | 命令行 | | [tacet](https://github.com/n24q02m/tacet) | 一种自蒸馏神经符号级联架构，可在知识...中分摊大模型成本 | 工具 | | [web-core](https://github.com/n24q02m/web-core) | 用于搜索、抓取、HTTP 安全和 st...的共享 Web 基础设施包 | 库 | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | 面向 AI Agent 的开源 MCP 服务：网页搜索、内容提取和 lib... | MCP |

目录

• 功能
• 安装
• Smithery
• 文档
• 工具
• 比较
• 配置
• 命令行
• 安全
• 从源代码构建
• 信任模型
• 许可证

功能

• 17 个复合超级工具 ——场景、节点、脚本、着色器、动画、TileMap、物理、音频、导航、UI 等
• 全面控制场景 ——直接创建、解析和修改 .tscn 文件，无需运行 Godot
• GDScript 增删改查 ——一次调用即可创建、读取、写入并附加脚本
• 分层 token 优化 ——精简描述 + 按需使用 help 工具

安装

默认通过 stdio 运行。无需凭据、账号或中继——服务会直接读取和写入本地 Godot 项目文件。文件操作可选用 Godot 4.x；只有 run/stop/export 和 editor 操作需要 Godot 二进制文件。检测器接受 Godot >=4.1。目前已使用 Godot 4.7.1 stable 验证实时引擎兼容性；这并不表示已验证所有未来的小版本。

通过 npx 安装（推荐）

npx -y @n24q02m/better-godot-mcp@latest

MCP 客户端配置

将以下内容添加到客户端的 MCP 配置中（Claude Code、Cursor、Windsurf、Codex、mcp.json）：

{
  "mcpServers": {
    "better-godot-mcp": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "/path/to/your/godot/project"
      }
    }
  }
}

GODOT_PROJECT_PATH 是可选的——每个工具调用也都接受 project_path 参数。

通过 Docker 安装

docker run -i --rm -v /path/to/your/godot/project:/project n24q02m/better-godot-mcp

该镜像提供 amd64 和 arm64 版本。挂载项目目录，以便服务读取和写入场景、脚本和资源文件。

Smithery

better-godot-mcp 提供 smithery.yaml，以便通过 Smithery 发现和部署。Smithery 通过 npx -y @n24q02m/better-godot-mcp 以 stdio 启动服务，无需配置即可启动——服务不需要凭据，并会直接读取本地 Godot 项目文件。

文档

完整的设置指南见 mcp.n24q02m.com/servers/better-godot-mcp/setup/——包含 Claude Code、Codex、Gemini CLI、Cursor、Windsurf 和 mcp.json 的安装步骤。

使用 AI Agent 安装——将以下内容粘贴给你的 AI 编码 Agent：

按照以下步骤安装 MCP 服务 better-godot-mcp： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-godot-mcp/setup-with-agent.md

工具

工具	操作	描述
project	info, version, run, stop, settings_get, settings_set, export	项目元数据、运行/停止和设置
scenes	create, list, info, delete, duplicate, set_main	场景文件管理
nodes	add, remove, rename, list, set_property, get_property	场景树节点操作
scripts	create, read, write, attach, list, delete	GDScript 文件增删改查
editor	launch, status	启动 Godot 编辑器并检查状态
config	status, set, detect_godot, check	服务配置和环境检测
resources	list, info, delete, import_config	资源文件管理
input_map	list, add_action, remove_action, add_event	输入操作和事件映射
signals	list, connect, disconnect	信号连接
animation	create_player, add_animation, add_track, add_keyframe, list	动画播放器和轨道
tilemap	create_tileset, add_source, set_tile, paint, list	TileMap 和 TileSet 管理
shader	create, read, write, get_params, list	使用 Godot 4 语法进行着色器文件增删改查
physics	layers, collision_setup, body_config, set_layer_name	碰撞层和物理体
audio	list_buses, add_bus, add_effect, create_stream	音频总线和效果管理
navigation	create_region, add_agent, add_obstacle	导航区域、Agent 和障碍物
ui	create_control, set_theme, layout, list_controls	UI 控件创建和主题设置
help	-	获取任意工具的完整文档

对比

better-godot-mcp 在各项能力上与直接竞品的对比：

能力	better-godot-mcp	Coding-Solo/godot-mcp	bradypp/godot-mcp	tugcantopaloglu/godot-mcp
场景文件管理	支持（scenes：创建/列出/查看信息/删除/复制/设为主场景）	支持（创建/保存）	支持（创建/保存）	支持（创建/读取/修改）
节点树操作	支持（nodes：添加/移除/重命名/列出/获取和设置属性）	部分支持（仅添加）	支持（添加/编辑/移除）	支持（添加/移除/重新设置父节点）
GDScript 文件 CRUD	支持（scripts：创建/读取/写入/附加/列出/删除）	不支持	不支持	部分支持（从模板创建 + 运行时求值）
Shader 文件 CRUD	支持（shader：创建/读取/写入/获取参数/列出）	不支持	不支持	部分支持（创建/读取 .gdshader）
动画创作	支持（animation：播放器/轨道/关键帧）	不支持	不支持	支持（播放器/tween/状态机）
TileMap / TileSet	支持（tilemap：图块集/来源/设置图块/绘制）	不支持	不支持	支持（TileMapLayer 单元格）
物理层/物理体	支持（physics：层/碰撞/物理体配置）	不支持	不支持	支持（碰撞/关节/射线检测）
音频总线管理	支持（audio：总线/效果/流）	不支持	不支持	支持（总线/路由/效果）
导航设置	支持（navigation：区域/Agent/障碍物）	不支持	不支持	支持（导航）
UI 控件创作	支持（ui：控件/主题/布局）	不支持	部分支持（通过添加节点）	支持（控件/主题/菜单）
输入映射编辑	支持（input_map：动作/事件）	不支持	不支持	支持（动作/按键绑定）
信号连接	支持（signals：连接/断开/列出）	不支持	不支持	支持（连接/发出/等待）
启动编辑器/运行项目	支持（editor、project 运行/停止）	支持	支持	支持
无需运行编辑器即可工作	支持（基于文本解析 .tscn）	支持（无头 GDScript 桥接）	支持（无头 GDScript 桥接）	部分支持（CLI 无头模式或实时 TCP 套接字）
不存储凭据（TC-Local）	支持	支持	支持	支持
stdio + HTTP 传输	支持（默认使用 stdio + --http）	不支持（仅 stdio）	不支持（仅 stdio）	不支持（仅 stdio）
Docker 镜像（amd64 + arm64）	支持	不支持	不支持	不支持
按 Token 分级的工具描述	支持（精简描述 + 按需使用 help）	不支持	不支持	不支持

配置

系统会从常见安装位置和 PATH 自动检测 Godot 二进制文件。基本用法不需要环境变量。也可以选择设置 GODOT_PROJECT_PATH 和 GODOT_PATH 来覆盖默认值。

变量	必填	默认值	描述
GODOT_PROJECT_PATH	否	-	默认项目路径（工具也接受 project_path 参数）
GODOT_PATH	否	自动检测	Godot 二进制文件的路径

HTTP 传输

服务默认通过 stdio 运行。如需改用 Streamable HTTP 提供服务，请传入 --http 或设置 MCP_TRANSPORT=http（也接受 TRANSPORT_MODE=http）。HTTP 模式会公开一个无需身份验证的 /mcp 端点——由于没有需要保护的凭据，因此该模式适用于可信的本地环境或可自托管场景。

变量	必填	默认值	描述
MCP_TRANSPORT	否	stdio	设置为 http 以使用 Streamable HTTP 传输
PORT	否	0（自动分配）	HTTP 端口（仅限 HTTP 模式）
HOST	否	服务默认值	HTTP 主机（仅限 HTTP 模式）

限制

• 需要采用 Godot 4.x 项目结构；文件操作不要求安装 Godot 二进制文件
• 场景文件（.tscn）通过文本操作进行解析和修改，而非使用 Godot 内部 API
• run/stop/export 操作要求已安装 Godot 二进制文件
• Docker 模式的文件系统访问受限（请挂载项目目录）

CLI

better-godot-mcp 二进制文件默认运行 MCP 服务（stdio；添加 --http 可使用 Streamable HTTP）。它还提供两个诊断子命令，可在配置 MCP 客户端之前检查 Godot 环境。

命令	描述
better-godot-mcp	启动 MCP 服务（默认使用 stdio；使用 --http 可使用 Streamable HTTP）
better-godot-mcp detect	以 JSON 格式输出检测到的 Godot 二进制文件信息（路径、版本、来源）；未找到时以非零状态码退出
better-godot-mcp doctor	对 Godot 二进制文件和当前项目进行健康检查（使用 GODOT_PROJECT_PATH，否则使用工作目录）

# Detect the Godot binary (JSON output)
npx -y @n24q02m/better-godot-mcp detect

{
  "found": true,
  "path": "/path/to/godot",
  "version": {
    "major": 4,
    "minor": 7,
    "patch": 1,
    "label": "stable.official",
    "raw": "4.7.1.stable.official"
  },
  "source": "system"
}

# Health-check the Godot binary and project
npx -y @n24q02m/better-godot-mcp doctor

[ok] godot binary: /path/to/godot (source: system)
[ok] godot version: 4.7.1.stable.official
[warn] project: no project.godot found at /path/to/cwd (set GODOT_PROJECT_PATH)

找不到 Godot 二进制文件时，detect 以 1 状态码退出；二进制文件缺失时，doctor 以 1 状态码退出（缺少 project.godot 仅会发出警告）。

安全性

• 二进制文件检测 -- 从多个路径检测 Godot（环境变量、PATH、常见位置）
• 项目验证 -- 操作前验证 project.godot 是否存在
• 跨平台 -- 处理 Windows、macOS、Linux 路径

从源代码构建

git clone https://github.com/n24q02m/better-godot-mcp.git
cd better-godot-mcp
bun install
bun run dev          # stdio mode (default)
bun run dev:http     # Streamable HTTP mode

信任模型

此插件实现 TC-Local（无需身份验证，不存储凭据）。完整分类请参阅信任模型参考。

模式	存储	加密	谁可以读取你的数据？
stdio（默认）	不适用（无凭据）	不适用	不适用
HTTP 自托管	不适用（无凭据）	不适用	不适用

许可证

Apache-2.0 -- 参见 LICENSE。