godot_mcp

# Godot MCP 原生插件 (模型上下文协议) 一款强大的 Godot 引擎插件，通过模型上下文协议（MCP）集成 AI 助手（如 Claude 等）。使 AI 直接读取和修改您的 Godot 项目 - 场景、脚本、节点和资源 - 所有操作都通过自然语言进行。 ## 功能 - **完全项目访问权限**：AI 助手可以读取和修改脚本、场景、节点和资源 - **原生实现**：无需 Node.js 依赖 - 完全在 Godot 内运行 - **实时编辑**：直接在编辑器中应用 AI 建议 - **全面的工具集**： - **节点工具**：创建、修改、管理工作场景节点，复制、移动、重命名、信号连接、锚点预设、分组管理、批量操作、场景审计 - **脚本工具**：修补、分析、创建、附加、验证 GDScript 文件，执行脚本，搜索文件，符号索引，定义和引用查找 - **场景工具**：操作场景结构，保存场景，列出/打开/关闭场景选项卡，项目场景列表 - **编辑器工具**：控制编辑器功能，截图，信号检查，文件系统重新加载，节点/文件选择，导出管理，属性检查器 - **调试工具**：日志记录，调试器会话，断点，堆栈/变量检查，性能分析，运行时探测，动画/音频/着色器/图块地图运行时控制，调试执行控制 - **项目工具**：访问目标项目设置，列出项目文件，创建资源，运行测试，管理输入映射，检查自动加载/全局类，重命名项目路径/类，资源诊断和健康审计 ## 安装 ### 方法 1：资产库（推荐） 1. 打开您的 Godot 项目 2. 进入编辑器中的 **资产库** 选项卡 3. 搜索 "Godot MCP 原生插件" 4. 点击 **下载** 然后 **安装** ### 方法 2：手动安装 1. 下载或克隆此存储库 2. 将 `addons/godot_mcp` 文件夹复制到项目的 `addons/` 目录 3. 在 Godot 中打开项目 4. 进入 **项目 > 项目设置 > 插件** 5. 启用 "Godot MCP 原生插件" ## 使用 ### 启用插件 1. 打开 **项目 > 项目设置 > 插件** 2. 在列表中找到 "Godot MCP 原生插件" 3. 将状态设置为 **启用** ### 配置 MCP 服务器 插件提供两种传输模式： #### HTTP 模式（用于远程访问） - 最适合：基于网络的 AI 集成 - 配置：设置 `transport_mode = "http"` 并配置 `http_port`（默认：9080） - 可选：启用 `auth_enabled` 并设置 `auth_token` 以确保安全 ### 连接到 Claude 桌面版 首先，安装 `mcp-remote` 包： ```bash npm install mcp-remote ``` #### HTTP 模式配置 ```json { "mcpServers": { "godot-mcp": { "command": "npx", "args": [ "mcp-remote", "http://localhost:19080/mcp" ] } } } ``` ### 连接到 Cursor / Trae #### HTTP 模式配置 ```json { "mcpServers": { "godot-mcp": { "url": "http://localhost:9080/mcp" } } } ``` 使用身份验证： ```json { "mcpServers": { "godot-mcp": { "url": "http://localhost:9080/mcp", "headers": { "Authorization": "Bearer your-secret-token-here" } } } } ``` ### 连接到 Cline #### HTTP 模式配置 ```json { "mcpServers": { "godot-mcp": { "url": "http://localhost:9080/mcp", "type": "streamableHttp", "disabled": false, "autoApprove": [] } } } ``` ### 连接到 OpenCode #### HTTP 模式配置 ```json { "mcp": { "godot-mcp": { "type": "remote", "url": "http://localhost:9080/mcp" } } } ``` ### 连接到 Codex #### HTTP 模式配置 ```toml [mcp_servers] [mcp_servers.godot-mcp] type = "streamableHttp" url = "http://localhost:19080/mcp" ``` ## 示例提示 连接后，您可以通过 Claude 与 Godot 项目交互： ``` @mcp godot-mcp read godot://script/current 我需要帮助优化我的玩家移动代码。你能建议一些改进吗？ ``` ``` @mcp godot-mcp get-scene-tree 在场景中间添加一个立方体，并创建一个相机来观察它。 ``` ``` 创建具有 Play、Options 和 Quit 按钮的主菜单 ``` ``` 实现具有动态照明的日夜循环系统 ``` ## 可用命令 ### 节点写入（6） - `create-node` - 创建新节点 - `delete-node` - 删除节点 - `update-node-property` - 更新节点属性 - `duplicate-node` - 复制节点及其子节点 - `move-node` - 将节点移动到新父节点 - `rename-node` - 重命名场景中的节点 ### 节点读取（3） - `get-scene-tree` - 获取场景树结构 - `get-node-properties` - 获取特定节点的属性 - `list-nodes` - 列出父节点下的节点 ### 节点写入-高级 - `set-anchor-preset` - 为 Control 节点设置锚点预设 - `connect-signal` - 在节点之间连接信号 - `disconnect-signal` - 断开信号连接 - `set-node-groups` - 为节点设置分组 - `add-resource` - 添加资源子节点（碰撞形状、网格等） - `autofit_collision_shape_2d` - 将 CollisionShape2D 拟合到 Sprite2D 或 AnimatedSprite2D 范围 - `list-scene-animations` - 列出 AnimationPlayer 动画和轨道 - `upsert-scene-animation` - 创建/更新动画和值轨道 - `remove-scene-animation` - 删除 AnimationPlayer 动画 ### 节点-高级 - `get-node-groups` - 获取节点所属的组 - `find-nodes-in-group` - 查找特定组中的所有节点 - `batch-update-node-properties` - 在一个 UndoRedo 操作中批量更新多个节点属性 - `batch-scene-node-edits` - 在一个 UndoRedo 操作中应用批量场景节点创建/删除/移动编辑 - `build-tree` - 为 UI 和场景搭建原子化构建递归节点子树 - `audit-scene-node-persistence` - 审计节点所有者和场景持久化状态 - `audit-scene-inheritance` - 审计继承/实例化场景结构 ### 脚本（7） - `list-project-scripts` - 列出所有脚本 - `read-script` - 读取特定脚本 - `modify-script` - 更新脚本内容 - `create-script` - 创建新脚本 - `get-current-script` - 获取当前编辑的脚本 - `attach-script` - 将现有脚本附加到节点 - `execute-script` - 执行 GDScript 表达式 ### 脚本-高级 - `analyze-script` - 分析脚本结构 - `patch-script` - 应用精确匹配的脚本替换，并带有解析检查回滚 - `validate-script` - 验证 GDScript 语法 - `search-in-files` - 搜索项目文件 - `list-project-script-symbols` - 索引 GDScript 和 C# 文件中的脚本符号 - `find-script-symbol-definition` - 查找脚本符号的定义位置 - `find-script-symbol-references` - 查找脚本符号的文本引用 - `rename-script-symbol` - 在项目文件中重命名脚本符号 - `open-script-at-line` - 在编辑器中打开脚本到特定行 ### 场景（4） - `create-scene` - 创建新场景 - `save-scene` - 保存当前场景 - `open-scene` - 打开场景 - `get-current-scene` - 获取当前场景信息 ### 场景-高级（4） - `list-project-scenes` - 列出所有场景 - `get-scene-structure` - 获取场景结构详情 - `list-open-scenes` - 列出当前打开的场景选项卡 - `close-scene-tab` - 关闭场景选项卡 ### 编辑器（4） - `get-editor-state` - 获取当前编辑器状态 - `run-project` - 运行项目 - `stop-project` - 停止运行的项目 - `execute-editor-script` - 执行 GDScript 脚本 ### 编辑器-高级 - `get-selected-nodes` - 获取选定的节点 - `set-editor-setting` - 修改编辑器设置 - `get-editor-screenshot` - 捕获编辑器视口截图 - `get_game_screenshot` - 通过 MCPGameBridge 捕获运行游戏的视口截图 - `get-signals` - 检查节点信号和连接 - `reload-project` - 重新扫描项目文件系统 - `select-node` - 在场景中选择节点并在检查器中聚焦 - `select-file` - 在文件系统停靠中选择文件 - `get-inspector-properties` - 检查节点/资源属性，如检查器 - `list-export-presets` - 列出导出预设 - `inspect-export-templates` - 检查已安装的导出模板 - `validate-export-preset` - 验证导出预设 - `run-export` - 运行 Godot CLI 导出 ### 调试 - `get-editor-logs` - 获取编辑器/运行时日志 - `debug-print` - 打印调试信息 - `clear-output` - 清除 MCP/编辑器输出缓冲区 - `get-performance-metrics` - 获取性能数据 - `get-debugger-sessions` - 列出编辑器调试器会话和活动/中断状态 - `read_game_logs` - 读取由 MCPGameBridge 捕获的运行游戏日志 - `clear_game_logs` - 清除 MCPGameBridge 运行时日志缓冲区 - `set-debugger-breakpoint` - 启用或禁用调试器断点 - `send-debugger-message` - 向运行的游戏调试器发送自定义消息 - `toggle-debugger-profiler` - 在活动会话中切换 EngineProfiler 通道 - `get-debugger-messages` - 读取由桥梁捕获的自定义运行时消息 - `add-debugger-capture-prefix` - 捕获额外的 EngineDebugger 消息前缀 - `get-debug-stack-frames` - 从中断会话中读取捕获的脚本堆栈帧 - `get-debug-stack-variables` - 读取捕获的堆栈帧的局部变量、成员和全局变量 - `install-runtime-probe` - 将 MCP 运行时探测节点添加到当前场景 - `remove-runtime-probe` - 从当前场景中删除 MCP 运行时探测节点 - `request-debug-break` - 要求运行时探测进入 Godot 的调试中断循环 - `send-debug-command` - 向中断会话发送逐步/下一步/下一步/继续/堆栈调试器命令 - `get-runtime-info` - 通过探测查询运行时指标（FPS、节点数等） - `get-runtime-scene-tree` - 从运行的游戏中读取实时的场景树 - `inspect-runtime-node` - 检查实时的节点及其可序列化属性 - `update-runtime-node-property` - 修改实时节点的属性 - `call-runtime-node-method` - 在实时节点上调用方法 - `evaluate-runtime-expression` - 在运行的游戏中评估 GDScript 表达式 - `await-runtime-condition` - 轮询运行时表达式直到真实或超时 - `assert-runtime-condition` - 断言运行时表达式在超时内变为真实 - `get-debug-threads` - 返回 DAP 样式的调试器线程 - `get-debug-state-events` - 读取记录的调试器状态转换 - `get-debug-output` - 读取分类的运行时调试器输出 - `get-debug-scopes` - 将堆栈变量分组为类似 DAP 的范围 - `get-debug-variables` - 解析 DAP 样式的变量引用 - `expand-debug-variable` - 通过范围和路径扩展调试变量 - `evaluate-debug-expression` - 在调试器上下文中评估表达式 - `debug-step-into` / `debug-step-over` / `debug-step-out` / `debug-continue` - 调试执行控制 - `debug-step-into-and-wait` / `debug-step-over-and-wait` / `debug-step-out-and-wait` / `debug-continue-and-wait` - 带状态等待的调试执行 - `await-debugger-state` - 检查调试器会话执行状态 - `get-runtime-performance-snapshot` - 捕获运行时性能快照 - `get-runtime-memory-trend` - 捕获运行时内存趋势 - `create-runtime-node` - 在运行的游戏中创建节点 - `delete-runtime-node` - 从运行的游戏中删除节点 - `simulate-runtime-input-event` - 注入结构化 InputEvent - `simulate-runtime-input-action` - 注入 InputEventAction - `list-runtime-input-actions` - 列出运行时 InputMap 操作 - `upsert-runtime-input-action` - 创建/更新运行时 InputMap 操作 - `remove-runtime-input-action` - 删除运行时 InputMap 操作 - `list-runtime-animations` - 列出运行时 AnimationPlayer 动画 - `play-runtime-animation` - 播放运行时动画 - `stop-runtime-animation` - 停止运行时动画 - `get-runtime-animation-state` - 获取运行时动画播放状态 - `get-runtime-animation-tree-state` - 获取运行时 AnimationTree 状态 - `set-runtime-animation-tree-active` - 启用/禁用运行时 AnimationTree - `travel-runtime-animation-tree` - 遍历运行时动画状态机 - `get-runtime-material-state` - 解析运行时节点的材质绑定 - `get-runtime-theme-item` - 解析运行时 Control 主题项 - `set-runtime-theme-override` - 应用运行时主题覆盖 - `clear-runtime-theme-override` - 删除运行时主题覆盖 - `get-runtime-shader-parameters` - 列出运行时着色器参数 - `set-runtime-shader-parameter` - 更新运行时着色器统一变量 - `list-runtime-tilemap-layers` - 列出运行时 TileMap 层 - `get-runtime-tilemap-cell` - 获取运行时 TileMap 单元格数据 - `set-runtime-tilemap-cell` - 写入/擦除运行时 TileMap 单元格 - `list-runtime-audio-buses` - 列出运行时音频总线 - `get-runtime-audio-bus` - 获取运行时音频总线状态 - `update-runtime-audio-bus` - 更新运行时音频总线 - `get-runtime-screenshot` - 捕获运行时视口截图 ### 项目 - `get-project-info` - 获取项目信息 - `get-project-settings` - 获取项目设置 - `get-project-setting` - 读取一个 ProjectSettings 值 - `set-project-setting` - 写入一个 ProjectSettings 值 - `list-project-resources` - 列出项目资源 - `list-project-files` - 列出类型化的项目文件，可选的 glob 过滤 - `read-project-text-file` - 读取 res:// 下的文本 - `write-project-text-file` - 写入 res:// 下的文本并刷新编辑器文件系统 - `list-user-files` - 列出 user:// 下的文件 - `read-user-text-file` - 读取 user:// 下的文本 - `batch-execute` - 在一个请求中顺序执行多个原生 MCP 工具调用 - `create-resource` - 创建新资源 - `set-resource-property` - 设置并保存一个资源属性 - `call-resource-method` - 调用资源方法并可选保存 - `theme_set_color` - 设置主题颜色条目 - `theme_set_constant` - 设置主题整数常量 - `theme_set_font_size` - 设置主题字体大小 - `theme_set_stylebox_flat` - 创建并分配 StyleBoxFlat 主题条目 - `get-project-structure` - 获取项目目录结构 - `list-project-tests` - 发现并列出可运行的项目测试 - `run-project-test` - 运行单个项目测试 - `run-project-tests` - 运行多个项目测试 - `run-scene-headless` - 在有界定 subprocess 中运行场景，支持驱动验证 - `list-project-input-actions` - 列出项目 InputMap 操作 - `upsert-project-input-action` - 创建或更新项目 InputMap 操作 - `remove-project-input-action` - 删除项目 InputMap 操作 - `list-project-autoloads` - 列出项目自动加载项 - `add-project-autoload` - 注册项目自动加载 - `remove-project-autoload` - 删除项目自动加载 - `list-project-global-classes` - 列出项目全局脚本类 - `get-class-api-metadata` - 获取 ClassDB 或全局类 API 元数据 - `docs_class_ref` - 获取紧凑的 ClassDB API 参考，适用于引擎类 - `inspect-csharp-project-support` - 检查 C# 项目支持文件 - `compare-render-screenshots` - 比较两个截图的像素差异 - `inspect-tileset-resource` - 检查 TileSet 资源 - `reimport-resources` - 通过导入管道重新导入资源 - `get-import-metadata` - 获取资源导入元数据 - `get-resource-uid-info` - 检查 ResourceUID 映射 - `fix-resource-uid` - 确保资源具有持久的 UID - `get-resource-dependencies` - 列出资源依赖 - `scan-missing-resource-dependencies` - 查找损坏的依赖引用 - `scan-cyclic-resource-dependencies` - 查找循环依赖链 - `detect-broken-scripts` - 扫描脚本的语法错误 - `validate-project` - 验证脚本、资源、UID、ext_resources 和场景信号连接 - `rename-project-path` - 移动项目文件并重写路径表单引用 - `rename-project-class` - 重命名类名并重写项目引用 - `audit-project-health` - 运行项目健康审计 ## 安全建议 - **生产环境**：始终启用身份验证（`auth_enabled = true`） - **令牌**：使用强令牌（至少 16 个字符，包含字母、数字和特殊字符） - **存储**：不要将令牌提交到版本控制 - **远程访问**：使用 HTTPS（TLS/SSL）进行网络访问 ## 需求 - Godot 引擎 4.x（推荐 4.5 或更高版本） - 无需额外依赖（原生实现） ## 文档 有关详细文档，请参阅 `docs/current/` 文件夹： - [快速入门指南](docs/current/quickstart.md) - [架构设计](docs/current/architecture.md) - [工具参考](docs/current/tools-reference.md) - [测试指南](docs/current/testing-guide.md) ## 贡献 欢迎贡献！请随时提交拉取请求。 ## 许可 该项目使用 MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 作者 **yurineko73** ## 致谢 - Godot 引擎团队，感谢他们出色的游戏引擎 - 模型上下文协议（MCP）规范 - Anthropic 的 Claude AI，激发了此次集成 --- **注意**：这是一个社区插件，不与 Godot 引擎或 Anthropic 官方关联。