godot-mcp

# Godot MCP **通过模型上下文协议为Godot Engine提供AI支持的游戏开发** [](https://www.typescriptlang.org/) [](https://docs.godotengine.org/) [](https://godotengine.org/) [](https://modelcontextprotocol.io/) [](LICENSE) Godot MCP 将 AI 助手（Claude、Cursor、VS Code Copilot、OpenCode 和任何支持 MCP 的客户端）直接连接到 Godot 编辑器。它提供了 40 多个模块的 300 多种工具，涵盖了从场景构建和节点操作到运行时检查、输入记录、物理设置、动画创作、项目导出、插件管理和调试等所有功能。 AI 可以读取你的场景树、创建节点、编写脚本、模拟游戏输入、捕获屏幕截图、运行断言和批量修改场景中的属性，所有这些都通过单个 WebSocket 桥接。 📋 浏览 [完整的工具目录](https://keeveeg.github.io/godot-mcp/tools.html) — 带有描述的 300 多种工具的可搜索列表。 > 该项目是在多个 AI 模型的帮助下开发的：MiMo-V2.5-Pro、DeepSeek V4 Pro、DeepSeek V4 Flash 和 Qwen 3.7 Plus。 ## 目录 - [功能](#功能) - [架构](#架构) - [安装](#安装) - [配置](#配置) - [工具类别](#工具类别) - [故障排除](#故障排除) ## 功能 - **300+ 种工具**，适用于完整的 Godot 开发工作流程 - **实时场景操作**。在 AI 聊天中添加、删除、移动、重命名和重新配置节点，无需离开编辑器 - **运行时游戏检查**。查询实时场景树，在游戏过程中读写属性，并在运行的游戏中执行 GDScript - **输入记录和重放**。记录玩家会话，以可变速度重放，并模拟键盘/鼠标/操作输入 - **视觉测试与截图**。捕获编辑器和游戏视口的截图，进行视觉回归检查 - **动画创作**。创建剪辑、添加轨道、设置关键帧、构建状态机和配置混合树 - **物理设置**。添加身体、碰撞形状、射线、物理材料和配置层/掩码 - **音频管理**。添加播放器、配置总线布局、插入效果（混响、延迟、合唱等） - **导航**。设置区域、代理、烘焙导航网格和查询两点之间的路径 - **TileMap 编辑**。设置单元格、填充矩形、清除区域和读取瓷砖数据 - **主题和着色器工具**。创建主题、设置颜色/字体/样式框；创建、编辑和验证着色器 - **批量操作**。按类型查找节点、设置跨场景的属性、检测循环依赖 - **测试框架**。运行多步骤测试场景、断言节点状态、检查屏幕文本、运行压力测试 - **撤销/重做支持**。所有编辑器突变都通过 Godot 的内置撤销系统 - **自动端口扫描**。服务器和插件在 6505-6514 端口上自动协商 - **零项目修改**。插件作为标准 Godot 插件安装，无需修改引擎 ## 架构 ``` +-----------------------------------------------------------------------+ | MCP 客户端（Claude、Cursor、VS Code、OpenCode） | | | stdio (JSON-RPC 2.0) | +-----------------------------------------------------------------------+ | v +-----------------------------------------------------------------------+ | Node.js MCP 服务器（TypeScript） | | server/src/index.ts | | | | +----------------+ +----------------+ +-------------------------+ | | | 工具注册表 | | WebSocket | | JSON-RPC 2.0 | | | | （40+ 模块） | | 服务器 | | 桥接 | | | +-------+--------+ +-------+--------+ +-------------------------+ | | | | | | | +--------------+ | | | | :6505-6514 （自动端口扫描） | | v v | +-----------------------------------------------------------------------+ | | WebSocket (JSON-RPC 2.0) v +------------------------------------------------------------------------+ | Godot 编辑器插件（GDScript） | | | | +------------------------------------------------------------------+ | | | addons/godot_mcp/ | | | | +----------------+ +----------------+ +--------------------+ | | | | | WebSocket | | 命令 | | 撤销/重做 | | | | | | 客户端 | | 路由器 | | 助手 | | | | | +----------------+ +----------------+ +--------------------+ | | | | +------------------------------------------------------------+ | | | | | 命令模块（40+ 文件，300+ 工具） | | | | | | 项目 | 场景 | 节点 | 脚本 | 编辑器 | 输入 | ... | | | | | +------------------------------------------------------------+ | | | +------------------------------------------------------------------+ | | | | +------------------------------------------------------------------+ | | | 运行时自动加载（mcp_runtime.gd） | | | | - 运行时场景树查询 | | | | - 游戏过程中属性读写 | | | | - 输入模拟和记录 | | | | - 截图 | | | | - 信号监视 | | | +------------------------------------------------------------------+ | +------------------------------------------------------------------------+ ``` **数据流：** 1. AI 客户端通过 stdio（JSON-RPC 2.0）发送工具调用 2. MCP 服务器接收它，在注册表中查找工具 3. 服务器通过 WebSocket 将调用转发到 Godot 编辑器插件 4. 插件的命令路由器分派到正确的命令模块 5. 命令模块调用 Godot 编辑器 API（带有撤销/重做包装以进行突变） 6. 结果流回：插件 -> WebSocket -> MCP 服务器 -> stdio -> AI 客户端 ## 安装 ### 先决条件 - **Godot 4.x**（已测试 4.7） - 支持 MCP 的 AI 客户端（Claude Desktop、Cursor、带有 Copilot 的 VS Code、OpenCode 等） ### Godot 插件安装 1. 将 `addon/godot_mcp/` 复制到项目的 `addons/` 目录中。 2. 在 Godot 中打开项目。 3. 转到 **项目 -> 项目设置 -> 插件**。 4. 在列表中找到 **Godot MCP** 并将其设置为 **活动**。 5. 插件将扫描 6505-6514 端口以查找正在运行的 MCP 服务器。连接后，**MCP** 选项卡将出现在底部面板中，显示连接状态和活动日志。 ## 配置 ### MCP 客户端 将以下内容添加到 MCP 客户端的配置文件中： ```json { "mcpServers": { "godot": { "command": "npx", "args": ["-y", "@keeveeg/godot-mcp"] } } } ``` 在本地开发环境中，使用完整路径： ```json { "mcpServers": { "godot": { "command": "node", "args": ["/path/to/godot-mcp/server/dist/index.js"] } } } ``` | 客户端 | 配置文件 | | -------------- | ---------------------------------------------------------------------------------------------------------------------- | | Claude Desktop | `~/.config/claude/claude_desktop_config.json`（Linux/macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows） | | Cursor | 项目根目录中的 `.cursor/mcp.json` | | OpenCode | 项目根目录中的 `opencode.json` 或全局 `~/.config/opencode/opencode.json` | `opencode.json` 示例： ```json { "mcp": { "godot": { "type": "local", "command": ["npx", "-y", "@keeveeg/godot-mcp"] } } } ``` ### 环境变量 | 变量 | 默认值 | 描述 | | ----------------- | ------- | ------------------------------------------------------ | | `GODOT_MCP_DEBUG` | （未设置） | 将其设置为任何值以在服务器中启用调试日志 | ### 工具启用/禁用 在 Godot 项目根目录中创建一个 `godot_mcp_config.json` 文件，以选择性地禁用工具： ```json { "enabled_tools": { "delete_scene": false, "reload_project": false, "execute_editor_script": false } } ``` 配置文件中未列出的工具默认为启用。插件在启动时读取此文件。 ## 工具类别 所有 300+ 种工具按类别组织。每种工具都映射到 Godot 编辑器操作。 ### 项目 查询项目元数据，浏览文件系统树，搜索文件名称或内容，读写 `project.godot` 中的项目设置，将 Godot UID 转换为文件路径。 ### 场景 场景的全生命周期管理：创建具有指定根节点类型的场景，打开和保存场景文件，从磁盘删除场景，将场景引用实例化为子节点，在编辑器中播放和停止场景，列出所有已加载的场景。 ### 节点 核心场景树操作：添加、删除、复制、移动和重命名节点；读写节点的任何属性；连接和断开信号；管理节点组和编辑器选择；设置 Control 节点的锚点预设。 ### 脚本 GDScript 文件操作：列出项目中的所有脚本，读写脚本文件，通过替换文本段编辑脚本，将脚本附加到节点，验证脚本的语法错误，跨项目文件搜索。 ### 编辑器 与 Godot 编辑器交互：捕获编辑器和游戏截图，在编辑器上下文中执行任意 GDScript，读取错误和输出日志，重新加载插件和项目，检查节点上的信号连接。 ### 输入 在游戏过程中模拟玩家输入：发送键盘按键、鼠标点击和移动，触发 InputMap 中的输入操作，运行带有定时器的顺序输入链，管理项目的输入操作定义。 ### 运行时 深度运行时内省：查询实时场景树和节点属性，在游戏过程中执行 GDScript，捕获视口帧，监视属性随时间的变化，记录和重放会话，查找具有脚本或接近程度的节点，通过文本点击 UI 元素，监视信号发射。 ### 动画 动画创作和管理：列出、创建和删除 AnimationPlayer 上的动画；添加轨道和设置关键帧；构建和检查 AnimationTree 状态机和混合树；设置树参数；向状态机添加状态。 ### TileMap 2D 瓦片基级别编辑：设置单个单元格，填充矩形区域，读取单元格数据，清除区域，查询 TileSet 配置，列出所有使用的单元格坐标。 ### 主题 UI 主题创建和修改：创建主题资源，设置颜色、常量、字体大小和样式框，适用于特定的控件类型，检查现有主题的完整覆盖列表。 ### 着色器 着色器开发工作流程：创建和读取着色器文件，编辑着色器以替换文本，创建 ShaderMaterials 并将它们分配给节点，获取和设置着色器统一参数，列出项目中的所有着色器，验证着色器是否存在编译错误。 ### 资源 一般资源管理：读取 `.tres`/`.res` 文件，编辑资源属性，创建新资源，获取预览缩略图，管理自动加载单例，复制资源，按类型列出资源，检查资源依赖图。 ### 物理 物理身体和碰撞设置：添加和配置 RigidBody、CharacterBody 和 StaticBody 节点；添加碰撞形状；设置碰撞层和掩码；添加射线节点；创建和分配物理材料。 ### 3D 场景 3D 场景构建：添加具有基本形状的 MeshInstance3D 节点，配置 Camera3D 节点，设置 DirectionalLight3D、OmniLight3D 和 SpotLight3D，配置 WorldEnvironment，添加 GridMap 节点用于基于瓦片的 3D 级别，应用 StandardMaterial3D 或 ShaderMaterial。 ### 粒子 粒子系统创建和配置：创建 GPUParticles2D/3D 节点，设置 ParticleProcessMaterial 属性，配置颜色渐变，应用预设（火、烟、火花、雨、雪、彩带、魔法），设置发射形状，调整速度曲线。 ### 导航 寻路基础设施：添加 NavigationRegion2D/3D、NavigationAgent2D/3D 和 NavigationLink2D/3D 节点；烘焙导航网格；设置导航层和掩码；查询导航地图数据；查找两点之间的路径。 ### 音频 音频播放和总线管理：添加 AudioStreamPlayer、AudioStreamPlayer2D 和 AudioStreamPlayer3D 节点；创建和配置音频总线；插入混响、延迟、合唱和压缩器等效果；调整总线音量、静音和独奏；读取当前总线布局。 ### 批量 跨场景的批量操作：查找特定类型的所有节点，跟踪信号连接，在单个节点上设置属性，查找场景中对节点和脚本的引用，获取场景依赖关系，应用跨场景的属性更改，检测循环依赖。 ### 分析 项目健康度和复杂性分析：分析场景节点数、深度和资源使用情况；映射场景中的信号流和连接；查找未使用的资源；获取项目统计数据，如文件数、大小、节点类型和脚本语言。 ### 测试 针对正在运行的游戏的自动化测试：运行结合输入、等待和断言的多步骤测试场景；检查节点属性值和屏幕文本；生成实体并衡量压力下的性能；获取会话的聚合测试报告。 ### 配置文件 性能监控：从 Godot 的内置性能监视器读取 FPS、内存、物理、渲染和音频计数器，并查询编辑器级指标，如编译时间和资源加载时间。 ### 导出 项目导出管理：列出已配置的导出预设，为特定平台导出项目，验证项目的导出准备情况，查询可用的导出模板，创建新的导出预设。 ### 插件管理 插件和插件生命周期：列出所有已安装的插件及其版本和状态，从资产库、git 仓库或本地路径安装插件，卸载插件并清理其文件，更新插件到最新版本，配置插件设置。 ### 音频配置 高级音频总线布局管理：读取所有音频设置，包括总线布局和驱动程序信息，替换整个总线布局，添加或删除特定位置的单个总线，设置总线音量级别，检查总线上的所有效果及其属性。 ### 构建配置 构建管道配置：读取和设置构建配置预设，选择脚本后端，配置资源的导出过滤器，设置自定义功能标签，调整调试和优化选项，验证构建设置，获取特定平台的 CLI 导出命令。 ### 调试配置 调试和性能设置：读取和配置远程调试连接，启用或禁用内置性能分析器，设置游戏过程中的错误和警告处理行为，读取或清除编辑器日志。 ### 调试 交互式调试工作流程：设置和删除断点（带有可选条件），列出所有活动断点，检查暂停时的调用堆栈和局部变量，在上下文中评估 GDScript 表达式，单步执行、单步进入和继续执行。 ### 编辑器配置 编辑器外观和布局：读取所有编辑器设置，切换颜色主题，改变工作区布局，调整字体大小和 UI 缩放，保存和加载命名布局，重置为出厂默认设置。 ### 游戏玩法自动化 自动化游戏玩法测试：运行结合输入、等待和检查的脚本化游戏玩法场景；记录游戏玩法会话，捕获输入事件和游戏状态；重放记录；创建特定位置的测试角色；使用直接移动或寻路导航角色；断言多个游戏状态条件；等待特定游戏事件，带有超时。 ### 内存分析 内存诊断：获取按类别（静态、视频、纹理、缓冲区、对象）的详细内存使用情况，跟踪特定类随时间的对象创建，检测场景树和对象图中的潜在内存泄漏，按类计算活动对象，强制执行垃圾回收并报告释放的内存。 ### 节点配置 节点类型内省和预设：获取任何节点类型的默认属性值，应用配置预设（例如，平台方块，顶部-底部相机），浏览所有可用的节点类型按类别，检查信号、方法、枚举、常量和类型的完整类层次结构。 ### 物理配置 物理引擎调优：读取和设置重力向量和大小，改变物理模拟 tick 率，选择物理引擎后端，为碰撞层分配人类可读的名称，并为物理物体配置默认线性阻尼。 ### 平台导出 特定平台的构建管道：为特定目标平台导出，验证平台导出准备情况，列出已安装的导出模板，创建特定平台的导出预设，运行导出的构建并捕获其输出，并执行详细的平台导出验证。 ### 平台特定 移动和 Web 的平台配置：读取和写入特定平台的设置，配置 iOS 包 ID、团队 ID 和代码签名；设置 Android 包名称、密钥库和权限；配置 Web/HTML5 画布调整大小、线程和 PWA 支持；查询平台功能和构建验证。 ### 项目配置 项目设置和输入管理：读取和写入单个项目设置，获取所有设置（可选前缀过滤），将设置重置为默认值，管理整个输入映射（操作、无效区、事件映射），并配置自动加载单例排序。 ### 项目创建 新建项目脚手架：从头或从模板创建完整的 Godot 项目，搭建标准文件夹结构，将资产导入新项目，初始化 git 仓库并附上正确的 `.gitignore`，生成 README 和 LICENSE 文件，安装依赖和插件，验证项目结构，并列出可用模板。 ### 渲染配置 渲染管道设置：读取所有渲染设置，应用质量预设，切换渲染器，配置抗锯齿（MSAA、FXAA、TAA），调整阴影和全局照明质量，启用或禁用后处理，设置视口尺寸和拉伸模式，配置窗口大小和 vsync，并查询 GPU 信息和渲染统计。 ### 资源配置 资源类型系统：浏览所有已注册的资源类型，检查任何资源类型的可序列化属性及其类型，从模板或默认值创建资源文件，将文件作为资源导入并附上自定义设置，读取或更新资源导入设置。 ### 保存/加载 游戏状态持久性测试：保存当前游戏状态到编号槽位并附上元数据，从保存文件加载状态，列出和删除保存文件，并比较两个保存状态以获取其内容的差异。 ### 场景配置 场景结构元数据：检查场景继承链（实例化和继承的场景），切换节点的唯一名称标志，管理场景组和属于它们的节点，读取或设置场景根节点的元数据。 ### 视觉测试 视觉回归测试：拍摄附带场景上下文元数据的屏幕截图，逐像素比较屏幕截图并附上不匹配百分比，断言屏幕截图在阈值内与基准匹配，随时间记录多个帧用于回归测试，聚合视觉差异报告，并管理视觉基准以供未来比较。 ## 故障排除 ### 连接问题 **"Godot 编辑器未连接"** MCP 服务器正在运行，但 Godot 尚未连接。 - 确保 Godot 编辑器已打开并启用 MCP 插件 - 在 Godot 底部停靠栏的 **MCP** 面板中检查连接状态 - 验证没有防火墙阻止 localhost 连接到 6505-6514 端口 - 在 Godot 的输出日志中查找 `[MCP]` 消息 **"无法绑定到 6505-6514 范围内的任何端口"** 扫描范围内的所有端口均已占用。 - 检查是否已运行另一个 MCP 服务器实例 - 终止任何 stale `node` 进程：`pkill -f "godot-mcp"`（Linux/macOS）或使用任务管理器（Windows） - 服务器将自动尝试下一个可用端口 ### Godot 路径未找到 **工具返回关于缺少文件或路径的错误** - 使用 `res://` 前缀路径（例如 `res://scenes/main.tscn`） - 使用 `get_filesystem_tree` 验证项目结构 - 确保 Godot 项目是您所期望的（请检查 `get_project_info`） ### WebSocket 超时 **"请求在 30000ms 后超时"** Godot 编辑器响应时间太长。 - 编辑器可能正在忙（编译、加载大场景） - 检查是否有对话框阻止编辑器（插件在游戏过程中自动关闭大多数对话框） - 尝试再次请求 - 对于大型操作，编辑器可能需要更多时间 ### 插件未加载 **Godot 输出日志中没有 `[MCP]` 消息** - 验证 `addons/godot_mcp/` 目录是否位于正确位置 - 进入 **项目 -> 项目设置 -> 插件** 并检查 Godot MCP 是否出现 - 如果它出现但被禁用，请启用它 - 在输出日志中检查 GDScript 错误 - 尝试 **项目 -> 重新加载当前项目** ### 工具在游戏过程中无法工作 **运行时工具在游戏运行时返回错误** `mcp_runtime.gd` 自动加载必须存在于您的项目中，运行时工具才能工作。插件在 `project.godot` 中自动注册它，但请验证它是否存在： 1. 打开 `project.godot` 并检查 `[autoload]` 部分 2. 您应该看到：`mcp_runtime="res://addons/godot_mcp/services/mcp_runtime.gd"` 3. **重要**：请勿使用 `*` 前缀（例如 `*res://...`）— `*` 表示“仅限编辑器”，自动加载项在游戏中不会加载 4. 在 Godot 的输出日志中查找 `[MCP Runtime] Loaded and ready for IPC` 5. 如果自动加载项未显示，请尝试停止并重新启动游戏 ### 端口已被占用 **服务器日志显示 "端口 6505 已被占用"** 这是正常的。服务器将尝试端口 6506，然后是 6507 等，直到找到一个开放的端口。Godot 插件会扫描该范围内的所有端口，因此无论服务器落在哪个端口上，它都会找到它。