Godot MCP Server

什么是 Godot MCP Server？

Godot MCP Server 是一个社区开发的 godot mcp 集成，让 AI 助手可以通过 Model Context Protocol 启动 Godot 编辑器、运行项目、读取调试输出并编辑场景。它为智能体提供了与真实 Godot 项目之间的直接反馈循环。

该项目由 Coding-Solo 在 GitHub 上开发，采用 MIT 许可证，并以 @coding-solo/godot-mcp 发布在 npm 上。它不是 Godot Engine 官方产品。它通过 stdio 在本地运行，并调用你已安装的 Godot 可执行文件，因此除了 AI 客户端发送给模型的内容之外，数据不会离开你的电脑。

如何使用 Godot MCP Server？

README 中列出的前提条件：

• 系统中已安装 Godot Engine
• Node.js 18.0.0 或更高版本，以及 npm
• 支持 MCP 的 AI 客户端

不需要 API key。支持两个可选环境变量：

变量	用途
GODOT_PATH	Godot 可执行文件路径（覆盖自动检测）
DEBUG	设为 "true" 以启用详细的服务端调试日志

Claude Code

claude mcp add godot -- npx @coding-solo/godot-mcp

带环境变量：

claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx @coding-solo/godot-mcp

重启 Claude Code 后即可使用 Godot 工具。

Cursor

在界面中打开 Cursor Settings > Features > MCP，点击 + Add New MCP Server，填写名称 godot、类型 command、命令 npx @coding-solo/godot-mcp。可能需要点击服务器卡片右上角的刷新按钮来加载工具列表。如需按项目配置，可创建 .cursor/mcp.json：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@coding-solo/godot-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Claude Desktop、Cline 及其他客户端

任何兼容 MCP 的客户端（如 Claude Desktop 或 Cline）都可以使用 README 中的通用配置：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@coding-solo/godot-mcp"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}

对于 Cline，README 将该配置放在 cline_mcp_settings.json 中，并给出了一个 autoApprove 工具名列表，可用于跳过确认提示。

从源码构建

git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp
npm install
npm run build

然后让 MCP 客户端指向 build/index.js，而不是使用 npx。

Godot MCP Server 的主要功能

• 为指定项目启动 Godot 编辑器
• 以调试模式运行项目，并捕获控制台输出和错误
• 以编程方式启动和停止正在运行的项目
• 获取已安装的 Godot 版本，并在目录中查找 Godot 项目
• 读取项目结构和元数据
• 创建场景、添加带属性的节点、向 Sprite2D 节点加载精灵并保存场景（包括创建变体）
• 将 3D 场景导出为供 GridMap 使用的 MeshLibrary 资源
• 管理 Godot 4.4+ 项目的 UID

在底层，简单操作使用 Godot 内置的命令行接口，而创建场景、添加节点等复杂操作则通过一个打包的 GDScript 文件 godot_operations.gd 完成，该文件以 JSON 形式接收操作类型和参数。

Godot MCP Server 工具

服务器提供 14 个工具，分为四组：

• 编辑器与运行控制： launch_editor 为项目打开编辑器，run_project 运行项目并捕获输出，get_debug_output 返回当前日志和错误，stop_project 结束运行。智能体可以借此修改代码、运行游戏并查看出错原因。
• 项目发现： get_godot_version、list_projects 和 get_project_info 让智能体了解已安装的引擎版本以及项目内容。
• 场景编辑： create_scene、add_node、load_sprite、save_scene 和 export_mesh_library 无需手动打开编辑器即可创建和修改 .tscn 场景。
• UID 管理（Godot 4.4+）： get_uid 返回文件的 UID，update_project_uids 通过重新保存资源来刷新 UID 引用。

Godot MCP Server 的使用场景

• 与智能体一起调试： “运行我的项目，读取调试输出，并修复 player.gd 中的空引用错误。”
• 搭建场景： “创建一个以 CharacterBody2D 为根节点的新场景，添加一个 Sprite2D，并把 res://art/hero.png 加载进去。”
• 检查项目： “列出 ~/games 中的 Godot 项目，并告诉我平台跳跃游戏项目的结构。”
• 3D 关卡工具： “把 tiles 场景导出为 MeshLibrary，以便在 GridMap 中使用。”
• 升级到 Godot 4.4： “移动文件后，更新整个项目中的 UID 引用。”
• 快速冒烟测试： 每次修改后从 Claude Code 或 Cursor 运行游戏，并检查控制台中的错误。

Godot MCP Server 与替代方案对比

Godot MCP Server 是面向游戏引擎的多个社区 MCP 服务器之一。如果你使用其他引擎，Unity MCP 可将 AI 助手连接到 Unity 编辑器，Blender MCP 则为 Blender 3D 场景提供类似能力。GitHub 上还有其他独立的 Godot MCP 项目，工具集各不相同，选择前请对比它们的 README。Coding-Solo 版本的特点是通过 npx 即可简单安装，并专注于运行项目和捕获调试输出。

Godot MCP Server 常见问题排查

• 找不到 Godot： 将 GODOT_PATH 设置为 Godot 可执行文件的完整路径。
• 项目路径无效： 路径必须指向包含 project.godot 文件的目录。
• 连接问题： 确认服务器正在运行，然后重启 AI 助手。
• 从源码构建出错： 运行 npm install，确保所有依赖都已安装。
• Cursor 中看不到工具： 确认服务器已在 Settings > MCP 中列出并启用。README 指出，MCP 工具只能在 Cursor 的 Agent 聊天模式中运行。