Godot Mcp Server

Godot MCP 服务

让 AI 助手全面访问 Godot 编辑器。

使用 Claude、Cursor 或任何兼容 MCP 的 AI 更快地开发游戏——无需复制粘贴，也无需切换上下文。AI 可直接在运行中的 Godot 编辑器内读取、写入和操作场景、脚本、节点及项目设置。

Godot 4.4+ · 69 个工具 · 撤销/重做 · 交互式项目可视化工具 · MIT 许可证

---

快速开始

0. 安装 Node.js（一次性设置）

从 nodejs.org 下载并运行安装程序（LTS 版本）。这是一个标准安装程序——无需使用终端。

1. 安装 Godot 插件

无需克隆或构建——可直接通过 npx 运行。

Claude Desktop — 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-server"]
    }
  }
}

Cursor — 添加到 MCP 设置中（Settings → MCP → Add Server）：

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-server"]
    }
  }
}

兼容任何支持 MCP 的客户端（Claude Code、Cline、Windsurf 等）

2. 安装 Godot 插件

将 GitHub 仓库中的 addons/godot_mcp/ 文件夹复制到 Godot 项目的 addons/ 目录中。然后启用插件：Project → Project Settings → Plugins → Godot MCP → Enable。

或者在 Godot 编辑器中安装：前往 Asset Store 标签页（Godot 4.7+，搜索「Godlink MCP」），或 AssetLib 标签页（Godot 4.6 及更早版本，搜索「mcp」）→ 安装。

3. 连接

重启 Godot 项目。查看编辑器右上角——应会看到绿色的 MCP: Agent Active。现在可以开始使用了。

---

它能做什么？

6 个类别中的 32 个工具

类别	工具数	示例
文件操作	4	浏览目录、读取文件、搜索项目、创建脚本
场景操作	11	创建场景、添加/移除/移动节点、设置属性、附加脚本、指定碰撞形状和纹理
脚本操作	6	应用代码修改、验证语法、重命名/移动文件并更新引用
项目工具	9	读取项目设置、输入映射、碰撞层、控制台错误、场景树转储
资源生成	1	从 SVG 生成 2D 精灵
可视化	1	交互式浏览器项目地图

交互式可视化工具

运行 map_project，即可在 localhost:6510 打开基于浏览器的项目浏览器：

• 显示所有脚本及其关系的力导向图
• 点击任意脚本即可查看变量、函数、信号和连接
• 直接在可视化工具中编辑代码——更改会实时同步到 Godot
• 可编辑节点属性的场景视图
• 重构前查找引用位置

---

工作原理

┌─────────────┐    MCP (stdio)    ┌─────────────┐   WebSocket    ┌──────────────┐
│  AI Client   │◄────────────────►│  MCP Server  │◄─────────────►│ Godot Editor │
│  (Claude,    │                  │  (Node.js)   │   port 6505   │  (Plugin)    │
│   Cursor)    │                  │              │               │              │
└─────────────┘                  │  Visualizer  │               │  32 tool     │
                                 │  HTTP :6510  │               │  handlers    │
                                 └──────┬───────┘               └──────────────┘
                                        │
                                 ┌──────▼───────┐
                                 │   Browser     │
                                 │  Visualizer   │
                                 └──────────────┘

MCP 服务通过 Godot 插件使用 WebSocket 连接到 Godot 编辑器。AI 无需猜测项目结构——它会直接从运行中的编辑器读取实时状态。

---

当前限制

• 仅限本地 — 在 localhost 上运行，不支持远程连接
• 一次只能连接一个 Godot 编辑器 — 多个 AI 客户端可以同时连接，但它们共用一个 Godot 实例
• Ctrl+Z 无法撤销 AI 的更改 — 插件会写入磁盘，而非编辑器的实时场景树，因此 Godot 原生的撤销功能没有可还原的内容。请改用 mcp_undo 工具（让 Agent 执行撤销）。
• AI 对 Godot 的了解有限 — 它可以协助调试、编写脚本和构建场景，但无法在没有指导的情况下创建完整游戏

---

从源代码构建

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

然后将 AI 客户端指向 mcp-server/dist/index.js，而不是使用 npx。

---

许可证

MIT

---

GitHub · 报告问题