/ 目录 / 演练场 / Godot MCP
● 社区 Coding-Solo ⚡ 即开即用

Godot MCP

作者 Coding-Solo · Coding-Solo/godot-mcp

让 Claude 驱动 Godot 4——启动项目、无头运行场景、捕获 stdout/stderr,在不切换窗口的情况下迭代 GDScript。

Godot MCP 封装了 Godot 4 二进制文件,暴露编辑器和运行时工具。Claude 可以启动编辑器、无头运行项目、运行单个场景,并以文本形式拉取 stdout/stderr。配合 filesystem MCP,整个循环变成:Claude 编辑 .gd 文件 → 运行场景 → 读取错误 → 修复——全程在对话中完成。

为什么要用

核心特性

实时演示

实际使用效果

godot-mcp-coding-solo.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "godot-mcp-coding-solo": {
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "godot-mcp-coding-solo",
      "command": "npx",
      "args": [
        "-y",
        "godot-mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "godot-mcp-coding-solo": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "godot-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add godot-mcp-coding-solo -- npx -y godot-mcp

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Godot MCP

紧密迭代修复 GDScript bug

👤 独立/个人开发者 ⏱ ~20 min intermediate

何时使用: 重构后玩家移动出了问题,你希望 Claude 来修,不想每分钟切回 Godot。

前置条件
  • 已安装 Godot 4 — 从 godotengine.org 下载
  • GODOT_PATH 环境变量 — 指向 Godot 二进制(macOS 上不是 .app,而是 .app 内的二进制)
步骤
  1. 获取项目信息
    Godot:获取 /Users/me/games/Platformer 的项目信息,列出 autoload 和主场景。✓ 已复制
    → 返回项目名称、版本、autoload 列表
  2. 运行出问题的场景
    以无头模式运行场景 scenes/Level1.tscn,超时 10 秒,展示 stderr。✓ 已复制
    → 捕获到 stderr;错误行 + traceback 可见
  3. 修复并重新运行
    报错是「Invalid call to method move_and_slide on null」。读取 scripts/Player.gd,找出原因,修复它,然后重新运行场景。✓ 已复制
    → 文件已编辑,场景重新运行,null 错误消失

结果: 5 分钟内在对话中找到并修复 bug,不需要离开聊天窗口。

注意事项
  • 无头运行挂起在模态对话框上 — 使用 timeout;查看 stderr 中是否有对话框标题
  • GODOT_PATH 指向了错误的架构(Intel vs ARM mac) — 用 file $GODOT_PATH 验证
搭配使用: filesystem · github

从零搭建玩家状态机

👤 新项目起步的开发者 ⏱ ~25 min intermediate

何时使用: 想要 Idle/Run/Jump/Attack 的状态机样板,不想手动复制粘贴。

前置条件
  • 空白 Godot 项目 — 通过 Project Manager 创建
步骤
  1. 生成文件
    创建 scripts/State.gd(基类)以及继承它的 IdleState/RunState/JumpState/AttackState,用 signal 处理状态转换,保存到 res://scripts/states/。✓ 已复制
    → 正确位置生成了 5 个新 .gd 文件
  2. 接入 Player.gd
    更新 scripts/Player.gd,实例化状态机并将 _physics_process 委托给 current_state,保持输入处理最简化。✓ 已复制
    → Player.gd 包含 state_machine、current_state 和状态转换逻辑
  3. 冒烟测试
    运行 scenes/Player.tscn 3 秒,查找运行时错误。✓ 已复制
    → 运行正常;可以开始添加游戏逻辑

结果: 可用的状态机样板——随时可以添加真实状态。

注意事项
  • 忘记在 State.gd 中声明 class_name — 加上它,子类才能使用该类型
搭配使用: filesystem

在 CI 中无头运行 GUT 测试

👤 搭建 CI 的开发者 ⏱ ~30 min advanced

何时使用: 你希望每次 push 都在 GitHub Actions 中运行单元测试。

前置条件
  • GUT 测试插件 — 通过 Asset Library 安装,或作为 git submodule
步骤
  1. 先本地运行
    Godot:无头运行场景 addons/gut/gui/GutRunner.tscn,捕获退出码。✓ 已复制
    → 测试运行;全绿时退出码为 0
  2. 生成 workflow
    现在编写 .github/workflows/test.yml,在 Ubuntu 上使用 godot-headless 4.x 完成同样的操作。✓ 已复制
    → 包含正确 Godot setup action 的 workflow 文件

结果: 可重复运行的 Godot 测试 CI 流程。

注意事项
  • 无头模式因 display 调用而崩溃 — 使用 --headless,测试中避免 OS.window_*
搭配使用: github

组合

与其他 MCP 搭配,撬动十倍杠杆

godot-mcp-coding-solo + filesystem

编辑 GDScript 并在紧密循环中重跑场景

Filesystem:在 scripts/Player.gd 中添加跳跃冷却。Godot:运行 scenes/Player.tscn 3 秒,展示 stderr。✓ 已复制
godot-mcp-coding-solo + github

Claude 修复 gameplay bug 后提 PR

Godot:重跑场景确认 bug 已修复。GitHub:提 PR,附上修复内容和相关日志片段。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
get_project_info project_path: str 第一步,完整性检查 免费
launch_editor project_path: str 打开 Godot 编辑器界面 免费
run_project project_path, headless?: bool, timeout?: int 完整项目冒烟测试 免费
run_scene project_path, scene_path, headless?, timeout? 迭代单个场景 免费
stop_process pid: int 终止卡住的运行 免费

成本与限制

运行它的成本

API 配额
无——本地运行
每次调用 Token 数
200–8000(stdout/stderr 可能较大)
费用
开源免费;Godot 本身免费
提示
对 run_scene 积极使用 timeout;不要让死循环消耗 token

安全

权限、密钥、影响范围

最小权限: 执行 Godot 二进制
凭据存储:
数据出站: 仅限本地
切勿授予: 任意 shell 执行

故障排查

常见错误与修复

找不到 GODOT_PATH

设置 Godot 二进制的绝对路径;macOS 上使用 .app 内部的二进制

验证: $GODOT_PATH --version
无头运行挂起

始终传 timeout;查看 stderr 是否有模态对话框或 shader 编译

Godot 版本不对

MCP 仅支持 Godot 4.x;Godot 3.x 场景无法加载

验证: godot --version

替代方案

Godot MCP 对比其他方案

替代方案何时用它替代权衡
godot.unitynoid (mcp-godot)想用其他分支经验积累较少
Bevy / Rapier MCPs你在用 Rust/Bevy完全不同的引擎

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills