Funplay Godot MCP

Funplay MCP for Godot

面向 Godot 编辑器的先进 MCP 服务

Godot 资源商店 · 中文 | English

💖 如果你觉得这个项目有用，请考虑点个 Star。这能帮助更多 Godot 开发者发现它，也能支持项目持续开发。

Funplay MCP for Godot 是一个采用 MIT 许可证的 Godot 编辑器 MCP 服务，可让 Claude Code、Cursor、Windsurf、Codex 和 VS Code Copilot 等 AI 助手直接在运行中的 Godot 项目内操作。

此插件适用于标准 Godot 4.2+ 项目，也可用于 Godot .NET 项目。当前实现基于 GDScript，导出的脚本工具会根据语言提供相应支持：GDScript 项目可使用 GDScript 工作流，.NET 项目可使用 C#/.NET 工作流，混合项目则会在适用时同时提供两者。

用一句话描述你的游戏或工具，AI 助手就会通过 Funplay MCP for Godot 的内置工具在 Godot 中完成构建，涵盖场景创建、脚本生成、UI 编辑、运行模式验证、输入模拟、动画设置、摄像机控制、性能检查和编辑器自动化。

“构建一个俯视角射击游戏 HUD，包含生命值、弹药、暂停菜单和受击闪烁反馈”

AI 助手会通过 Funplay MCP for Godot 完成整个流程：创建场景结构、生成脚本、构建 Control 节点树、连接信号、配置动画并验证工作流——这一切只需一条提示词。

快速开始

如果你只想快速连接，请完成以下三步：

• 打开项目，或将 addons/funplay_mcp 复制到自己的 Godot 项目中
• 启用插件并启动 MCP 服务
• 使用内置的一键客户端配置

1. 安装插件

你可以：

• 从 Godot 资源商店安装，
• 从最新的 GitHub Release 下载 Funplay.GodotMcp.vX.Y.Z.zip 并解压到项目根目录，
• 克隆此仓库并直接将其作为 Godot 项目打开，或
• 将 addons/funplay_mcp 复制到自己的 Godot res://addons/ 目录

💡 克隆或安装前，如果能在 GitHub 上点个 ⭐，我们将不胜感激。

2. 启用并启动 MCP 服务

在 Godot 中：

• 打开 项目 → 项目设置 → 插件
• 启用 Funplay MCP for Godot
• 使用右侧的 Funplay MCP 停靠面板

服务默认在 http://127.0.0.1:8765/ 启动。 如果该端口已被占用，服务会自动选择另一个空闲的本地端口，并将其保存到 user://funplay_mcp_settings.cfg。 本地 MCP POST 请求需要每个项目专属的身份验证令牌，该令牌存储在 user://funplay_mcp_settings.cfg 中；停靠面板会自动将其写入生成的 stdio 客户端配置。 通过身份验证的客户端可以运行影响较大的编辑器工具，包括 execute_code；仅在使用可信本地客户端时启用服务，除非你确实需要覆盖安全检查，否则请保持检查开启。 停靠面板还会显示已安装的插件版本，并提供 检查更新操作；有新版本时，该操作会打开最新的 GitHub Release。 使用停靠面板顶部的 语言选择器切换英语和简体中文。所选语言会保存到 user://funplay_mcp_settings.cfg，并在下次打开项目时恢复。

3. 配置 AI 客户端

请先使用 Funplay MCP 停靠面板内置的 一键 MCP 配置。

选择目标客户端，点击 配置，插件便会为你写入推荐的 MCP 配置项。 如果还希望插件在项目本地的 res://.funplay/skills/ 下生成技能文件，并为会读取仓库说明的 AI 客户端生成 AGENTS.md 桥接文件，请使用 配置 + 技能。

如果 Godot 必须改用其他端口，请使用停靠面板中显示的端点。 如果你更愿意手动编辑配置文件，请将以下示例用作备用参考：

{
  "mcpServers": {
    "funplay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/",
        "FUNPLAY_GODOT_MCP_TOKEN": "<token from Funplay MCP dock>"
      }
    }
  }
}

{
  "mcpServers": {
    "funplay": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/",
        "FUNPLAY_GODOT_MCP_TOKEN": "<token from Funplay MCP dock>"
      }
    }
  }
}

{
  "servers": {
    "funplay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/",
        "FUNPLAY_GODOT_MCP_TOKEN": "<token from Funplay MCP dock>"
      }
    }
  }
}

[mcp_servers.funplay]
url = "http://127.0.0.1:8765/"

可选的 stdio 包装器

大多数客户端都可以通过 HTTP 直接连接插件。在 Godot 有符号 64 位范围内的整数 JSON-RPC 响应 ID 会序列化为整数，以兼容能够区分整数和浮点数的客户端。超出该范围的 ID 会保留原有表示形式。对于偏好使用 stdio 包的客户端或注册表，本仓库还包含一个可用于 npm 的包装器，位于 stdio-wrapper/ 下。

该包装器会将每个 HTTP 请求（包括其响应正文）的时长限制为 60 秒，避免卡住的请求无限期阻塞后续消息。

cd stdio-wrapper
npm link
FUNPLAY_GODOT_MCP_URL=http://127.0.0.1:8765/ funplay-godot-mcp

要安装已发布的包装器，请使用 npm install -g [email protected]，不要使用 npm link。

MCP 客户端配置项示例：

{
  "mcpServers": {
    "funplay": {
      "command": "funplay-godot-mcp",
      "env": {
        "FUNPLAY_GODOT_MCP_URL": "http://127.0.0.1:8765/"
      }
    }
  }
}

4. 验证连接

打开 AI 客户端，先尝试几个安全请求：

• “调用 get_scene_info，告诉我当前打开的场景是什么。”
• “读取 godot://project/context，并总结当前编辑器状态。”
• “使用 execute_code 返回当前活动场景的名称。”

如果这些请求成功，说明 MCP 服务、资源和主要执行工具均已正确连接。

5. 开始构建

打开 AI 客户端并尝试：“创建一个包含生命值条、分数标签和暂停按钮的 2D HUD”

开始之前

• 此插件仅用于编辑器。它不会向导出的游戏添加运行时组件。
• MCP 服务默认在 http://127.0.0.1:8765/ 上启动。如果同一项目已占用该端口，停靠面板会连接到该端口；否则会改用其他空闲本地端口。
• 本地 MCP 服务设置存储在 user://funplay_mcp_settings.cfg 中。
• 语言选择器仅用于本地化停靠面板界面；为保证兼容性，MCP 工具名称、协议字段和生成的客户端配置标识符仍保持英文不变。
• 插件默认使用 core MCP 工具配置，减少 AI 客户端中的工具列表冗余。如果需要完整的工具集，可在停靠面板中切换到 full。
• 停靠面板包含一个工具开放面板，可用于禁用当前配置中的单个工具，还提供可选的调试日志和 execute_code 安全开关。
• 默认情况下，execute_code 会对常见的进程、文件系统和项目设置变更进行安全检查。经审核的调用可以传入 safety_checks=false。
• 播放模式请求会延迟到 MCP 响应发送后执行，且重复调用具有幂等性。配置为运行多个实例的项目必须传入 allow_multiple_instances=true；仅在确实要重启时才使用 restart_if_running=true，随后检查 get_play_state，确认状态已切换。
• 停靠面板可以检查 GitHub Releases 中是否有较新版本的插件，并显示发布压缩包、清单、SHA256 和 server.json 文件是否存在。
• 指定的 MCP 工具会直接运行。插件内没有额外的审批开关。
• 内置停靠面板可为 Codex、Claude Code、Cursor 和 VS Code 复制或写入推荐的 MCP 配置项。

为什么选择本项目

• 以 execute_code 为核心 — 此插件围绕一个灵活性极高的 GDScript 执行工具进行优化，支持丰富的编辑器／运行时编排，并默认启用针对高风险代码片段的安全检查
• 工具暴露控制 — 无需编辑插件代码或重启项目，即可在 Godot 停靠面板中切换单个工具
• 停靠面板仪表板 — 在 Godot 中查看服务状态、工具暴露情况、运行时桥接心跳、发布就绪情况和项目地图操作
• 双语停靠面板 UI — 在英文和简体中文之间切换停靠面板控件、工具提示和运行状态，并按项目保存偏好设置
• 项目技能 — 生成项目本地的 AI 指导文件，其中包含当前端点、工具配置、项目上下文和推荐的 Funplay 工作流
• 工具目录与帮助 — 通过 MCP 查询分组工具目录、能力门槛、工作流覆盖范围和针对特定任务的指导
• 项目地图与模板 — 检查场景、脚本、函数、信号、使用关系链接、可搜索的浏览器图谱以及脚本重构计划的试运行结果
• 运行时桥接 — 可选安装轻量级自动加载项，用于播放模式心跳、场景树快照、节点查询、运行时截图、输入注入和事件历史
• 安全的播放模式自动化 — 排队并确认幂等的启动／停止状态转换，明确选择加入多实例运行，模拟输入，检查日志，并通过同一 MCP 会话验证行为
• 内置项目上下文 — 暴露有关项目状态、当前场景、选中项、播放状态、脚本错误、日志和 MCP 交互历史的实时资源
• 默认精简，需要时全面 — core 暴露精简且高信号的工具集；full 暴露更广泛的编辑器自动化功能
• 单一 Godot 插件 — 无需额外的审批 UI，且 Godot 端插件本身无需外部 Python 守护进程
• 可扩展 — 随着代码仓库不断发展，可添加更多 Godot 专用工具、资源、提示词和工作流助手

亮点

• 129 个内置工具 — 场景编辑、PackedScene 工作流、语言感知脚本工具、项目地图、脚本重构规划、项目设置、资源导入计划、输入映射、自动加载项、运行时桥接、撤销／重做、工作流指导、文件、项目技能、播放模式控制、UI 控件、动画、摄像机、性能、资源、提示词和编辑器自动化
• 资源与提示词 — 实时项目上下文、仪表板状态、JSON 和 HTML 项目地图、发布就绪情况、运行时场景树快照和事件历史、场景／选中项／错误资源、语言感知脚本诊断、适用时提供的 .NET 项目资源、模板资源以及可复用的工作流提示词
• 结构化结果 — JSON 工具输出和工具错误会同步到 MCP structuredContent 中，节点／资源摘要包含会话 instance_id 值，供后续调用使用
• 输入模拟 + 视图捕获 — 通过动作／按键／鼠标模拟驱动播放模式，并使用捕获的编辑器视图验证结果
• 一键配置客户端 — 直接通过 Godot 停靠面板为 Codex、Claude Code、Cursor 和 VS Code 生成 MCP 配置条目
• 已就绪，可发布和提交至注册表 — GitHub Release 会生成包含清单和 SHA256 校验和的构件，同时附带 Godot Asset Library 打包说明；npm stdio 包装器由 server.json 描述，发布就绪情况可通过 MCP 查看
• UI／控件工具 — 通过 MCP 构建 CanvasLayer 和 Control 层级结构、设置布局、应用主题覆盖、连接信号并创建 HUD
• 不依赖特定厂商 — 适用于任何支持 MCP 的 AI 客户端：Claude Code、Cursor、Windsurf、Codex、VS Code Copilot 等

与 Unity MCP 的比较

下表比较了此仓库与公开的 FunplayAI/funplay-unity-mcp 的行为和定位。

MCP 能力

当前开源包提供四个高价值能力层：

• 工具 — 共注册了 129 个工具，涵盖场景编辑、脚本、项目地图、项目配置、资源导入规划、输入映射、自动加载、运行时桥接、撤销/重做、工作流指导、文件、项目技能、UI、动画、相机、诊断和自动化。脚本相关工具会根据检测到的项目语言和停靠面板的 Tool Exposure 设置进行筛选。
• 主要执行方式 — 使用 execute_code 编排丰富的编辑器/运行时操作，默认启用安全检查，并提供可选的对象式上下文辅助工具、日志和变更跟踪元数据
• 提示词 — 工作流提示词，如 scene_review、feature_plan、runtime_debug、script_patch、ui_layout_plan、architecture_advice、performance_advice、network_template 和 template_generate
• 资源 — 项目上下文、仪表板状态、项目地图 JSON/HTML、场景摘要、选择状态、日志、脚本错误、运行状态、运行时场景树、运行时事件、发布就绪状态、项目功能、MCP 交互历史、模板目录和文件模板

内置工具

Funplay MCP for Godot 目前提供 129 个已注册的工具函数，涵盖主要工作流类别。根据检测到的项目语言和各工具的公开设置，会筛选出实际导出的脚本工具：

仓库布局

• addons/funplay_mcp/plugin.gd — Godot 编辑器插件入口
• addons/funplay_mcp/core/ — MCP 服务、工具、资源、提示词、设置和配置写入器
• addons/funplay_mcp/ui/ — Godot 停靠面板界面
• stdio-wrapper/ — 为无法直接连接 HTTP MCP 的客户端提供的 npm stdio 桥接
• server.json — stdio 包装器的 MCP Registry 元数据
• scripts/package_release.py — 发布构建产物并验证软件包
• scripts/run_godot_smoke.py — 用于验证运行时桥接命令的本地 Godot 冒烟测试运行器
• scripts/godot_runtime_bridge_smoke.gd — 运行器使用的无头 Godot 冒烟测试脚本
• ASSET_LIBRARY.md — Godot Asset Library 打包、提交和更新安全说明
• CHANGELOG.md — 面向用户的变更记录
• CONTRIBUTING.md — 贡献者工作流程
• RELEASE_CHECKLIST.md — 发布流程

贡献

请参阅 CONTRIBUTING.md。

许可证

此仓库采用 MIT 许可证。