FunseaAI Unity MCP

Funplay MCP for Unity

最先进的 Unity Editor MCP 服务

中文 | English

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

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

用一句话描述你的游戏——你的 AI 助手便会通过 Funplay MCP for Unity 内置的工具，在 Unity 中构建游戏，包括创建场景、生成脚本、验证运行时、模拟输入、分析性能和自动化编辑器操作。

“制作一款 10x10 网格的贪吃蛇游戏，包含食物生成、分数 UI 和游戏结束画面”

你的 AI 助手会通过 Funplay MCP for Unity 完成这一切：创建场景、生成所有脚本、设置 UI 并配置游戏逻辑——仅需一个提示词。

16 秒演示——AI 生成 3D 模型，并将其端到端集成到场景中。观看 HD MP4。

快速开始

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

• 通过 Git URL 安装 Unity 包
• 启动 Funplay > MCP Server
• 使用内置的一键客户端配置

1. 通过 UPM 安装（Git URL）

在 Unity 中，前往 Window → Package Manager → + → Add package from git URL：

https://github.com/FunplayAI/funplay-unity-mcp.git

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

可选：通过 OpenUPM 安装

如果你希望 Unity Package Manager 显示基于注册表的包版本历史并允许选择版本，请改为从 OpenUPM 安装，而不是从 Git 安装。

使用 OpenUPM CLI：

openupm add com.gamebooom.unity.mcp

或者在 Packages/manifest.json 中手动添加作用域注册表：

{
  "scopedRegistries": [
    {
      "name": "OpenUPM",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.gamebooom"
      ]
    }
  ],
  "dependencies": {
    "com.gamebooom.unity.mcp": "0.7.2"
  }
}

如果你之前通过 Git URL 安装，请先移除 Git 依赖项，再从 OpenUPM 安装。通过 Git 安装的包在 Unity 中只会显示解析后的 Git 版本，也不会显示基于注册表的 Version History 列表。

2. 启动 MCP 服务

通过 Funplay → MCP Server 启动服务。

每个新项目都会获得一个根据项目路径生成的独立端口，因此在不同项目中打开的两个编辑器不会争用同一个端口。MCP Server 窗口会显示准确的 URL（http://127.0.0.1:<port>/mcp/project/<project-id>/）；一键配置会为你写入该 URL。在 Server Port 中输入端口可固定使用某个端口（例如用于 CI 或防火墙规则），选择 Use Per-Project Port 则会改为按项目生成端口。

升级会保留现有的固定端口，但 v0.7.1 会将生成的 URL 绑定到项目。旧的根 URL 仍可读取；写入则需要经过验证的 expected_context。在现有的蓝色 Skills 通知卡片中重新运行 Reconfigure MCP + Skills 并重新连接客户端，或者明确传入来自独立验证的目标 Editor 的守卫信息。若希望该项目与另一个编辑器同时运行，请点击 Use Per-Project Port。完整设置指南请参阅同时运行多个 Unity 项目。

如果窗口报告正在使用备用端口，请勿使用仍指向被占用固定端口的客户端配置项，否则可能连接到占用该端口的进程。在你点击 Use Per-Project Port 或 Pin Current Port，且服务完成重启之前，一键配置会保持禁用。

默认传输方式为进程内直接 HTTP。如果需要在 Unity 脚本重新编译或 Play Mode 域重新加载时保持更稳定的连接，请在 MCP Server 窗口中启用 Experimental Broker Mode。它会使用 Unity 捆绑的 Mono 运行一个轻量本地代理，为 MCP 客户端保留相同的 127.0.0.1 端口，且无需更改客户端配置。

如果要编辑 core 或 full 实际公开的工具，请打开 Funplay → Tool Exposure。

如果需要调整 execute_code 的安全默认设置或插件调试日志，请打开 Funplay → MCP Settings。

3. 配置 AI 客户端

请先使用 Funplay > MCP Server 窗口内置的 One-Click MCP Configuration。

选择目标客户端，点击 Configure，软件包会为你写入推荐的 MCP 配置项。

对于 Claude Code、Cursor、Codex、OpenCode 和 DeepSeek Harness，点击 Configure + Skills 还会安装两个内置项目技能。

如果希望为当前 Unity 项目设置特定的 AI 指引，请打开 Funplay → Project Skills，选择受支持的平台，并安装内置的 unity-mcp-workflow 和 unity-ui-composition 技能。UI 技能涵盖响应式竖屏和横屏 uGUI 工作。

0.7.0 版保留了这两个内置技能，并新增了四份针对特定任务的参考资料，内容参考了 Unity 官方插件 0.1.8-beta：UI 框架选择、安全编辑 Sprite 导入器、TMP／本地化验证，以及软件包就绪情况。Agent 只会读取与其任务相关的参考资料；不会添加默认工具或额外技能。MCP 优先的操作方式、项目约定、预制体保留和设计还原度仍是首要准则。请通过 Project Skills 更新现有安装；缺失或过时的参考资料也会触发技能更新通知。用户拥有的参考文件不会被覆盖。

0.7.1 版为两个内置技能都添加了执行信任指南，包括项目身份、实际帧进度、严格的输入路由、自有验证清理，以及对阻塞性 Unity 原生对话框的条件处理。蓝色共享设置卡片会通过一个 Reconfigure MCP + Skills 操作报告 MCP 和 Skills 问题；解决其中一个问题时会保留另一个问题。请参阅执行信任与迁移。 如果你更喜欢手动编辑配置文件，请将以下示例用作备用参考。将 <project> 替换为此项目的条目名称，将 <port> 替换为其端口，并将 <project-id> 替换为完整绑定 URL 中的 ID——请从 MCP Server 窗口复制这些值，而不要从其他 Editor 窗口复制：

{
  "mcpServers": {
    "funplay-<project>": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

{
  "servers": {
    "funplay-<project>": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

[mcp_servers.funplay-<project>]
url = "http://127.0.0.1:<port>/mcp/project/<project-id>/"

{
  "mcp": {
    "funplay-<project>": {
      "type": "remote",
      "url": "http://127.0.0.1:<port>/mcp/project/<project-id>/",
      "enabled": true
    }
  }
}

# >>> funplay-mcp:funplay-<project> begin (managed by Funplay MCP -- reconfigure from Unity > Funplay > MCP Server)
# Funplay Unity MCP endpoint served by this editor; tools appear as mcp__funplay-<project>__<tool>.
- insert:
    - id: mcp-funplay-<project>
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: funplay-<project>
        transport: streamable-http
        url: http://127.0.0.1:<port>/mcp/project/<project-id>/
# <<< funplay-mcp:funplay-<project> end

{
  "mcpServers": {
    "funplay-<project>": {
      "serverUrl": "http://127.0.0.1:<port>/mcp/project/<project-id>/"
    }
  }
}

4. 验证连接

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

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

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

5. 开始构建

打开你的 AI 客户端并尝试：“创建一个有 5 个浮空平台的 3D 平台跳跃关卡”

开始之前

• 此软件包仅适用于 Editor。它不会向已构建的游戏添加运行时组件。
• 对于新项目，MCP 服务端口会按项目派生（范围为 20000-29999）；也可以固定端口。由较早版本升级的项目会保留现有端口并将其设为固定端口，你输入的任何端口也都会被固定。MCP Server 窗口会显示端口的来源和活动 URL。项目的客户端配置条目以项目目录命名（例如 funplay-love-town），因此配置多个项目时不会再覆盖同一个共享的 funplay 条目。两个项目若共用同一个目录名，解析出的条目名称也会相同；配置第二个项目时会自动附加项目哈希，因此不会覆盖任何内容，也无需启用任何设置。
• 本地 MCP 服务设置存储在 UserSettings/FunplayMcpSettings.json 中。
• 软件包默认使用 core：包含 40 个专注于结构化检查/编辑、UI 审查与创作、可恢复的 Editor 准备、共享任务状态、视觉证据、输入和日志的工具。简短的 MCP 任务可在一次响应中完成；get_task 支持有界等待和状态变更修订。execute_code 仍可作为项目专用的备用方案。full 保留全部 185 个工具，包括旧版状态/编译/Play API、验证管理、引用事务和专用诊断。自定义工具公开列表会保留；get_tool_capabilities 可区分实现情况、公开情况以及相关运行时后端的可用性。
• 生成的客户端 URL 按项目划分。执行写入前，请独立验证 initialize 响应中的项目身份。旧的根 URL 仍可读取，但修改操作需要经过验证的 expected_context；若不匹配，则不会执行任何工具。请参阅执行信任与迁移。
• 默认情况下，execute_code 安全检查和更严格的文件系统防护已从 Funplay > MCP Settings 启用。防护会阻止明显的破坏性代码片段、广泛的 System.IO 写入、原始文件流，以及绝对路径、用户路径、系统路径和路径遍历，但它并非完整的沙盒。客户端仍可在每次调用时通过可选参数 safety_checks 覆盖默认设置。
• 插件调试日志默认关闭，也可从 Funplay > MCP Settings 启用。警告和错误始终会写入 Unity Console。
• 所有公开的 MCP 工具都会直接运行，无需额外的审批开关。
• 菜单：Funplay > Check for Updates 可原位更新 Git 安装，或自动下载并导入最新的 unitypackage。

为什么开发此项目

• 优先使用结构化工具 — 使用专用工具完成常见的检查和编辑任务；遇到有防护措施的项目特定需求时，仍可使用内存中的 execute_code。参见 execute_code: In-Memory C# Execution。
• 默认启用安全检查 — execute_code 现在默认启用持久化安全开关，其中包括更严格的文件系统防护，适用于无法清晰展示每次调用参数的客户端
• 自动化 Play Mode — 进入 Play Mode、模拟键盘和鼠标输入、截取屏幕截图、检查日志，并在同一个 MCP 会话中验证行为
• 内置项目上下文 — 提供项目状态、活动场景、选中项、编译状态、控制台输出和 MCP 交互历史的实时资源
• 默认精简，需要时全面开放 — core 提供 40 个专用工具；full 提供全部 185 个内置工具
• 单个 Unity 包 — 无需额外的审批界面，无需点击确认外部守护进程，Unity 侧插件本身也不依赖 Python
• 可扩展 — 通过基于属性的发现机制添加自定义工具，也可按需将 Unity 连接到外部 MCP 服务

亮点

• 185 个内置工具 — 涵盖场景编辑、资源、脚本、Play Mode 控制、视觉证据、结构化检查、受控引用编辑和有界验证，共 43 个模块
• 结构化返回值 + instanceId 链式调用 — 工具以 {success, message, data} JSON 格式返回结果，并提供稳定的 instanceId 字段，让 Agent 能可靠地串联 by_id 调用，而不是按名称重新解析
• 供 execute_code 使用的 IFunplayCommand — 新的代码片段模板支持自动 Undo（ctx.RegisterObjectCreation/Modification/DestroyObject）、结构化日志（ctx.Log/LogWarning/LogError），并向 Agent 返回跟踪记录的变更日志
• 资源与提示词 — 提供实时项目上下文、场景／选中项／错误资源、资源模板，以及可复用的工作流提示词
• 输入模拟 + 屏幕截图 — 通过键盘／鼠标模拟驱动 Play Mode，并使用游戏／场景截图验证结果。v0.7.2 新增基于真实帧的连续鼠标／单指触控拖动、有界等待和受控清理；参见时序与后端限制。
• 内置更新功能 — 可从 Unity 菜单检查更新，并选择重新拉取 Git 包，或自动导入最新的 unitypackage
• 一键配置客户端 — 直接在 Unity 窗口中为 Claude Code、Cursor、Kimi、LM Studio、VS Code、Kiro、Trae、Codex、OpenCode、DeepSeek Harness、Antigravity 等客户端生成 MCP 配置项
• 工具开放范围控制 — 编辑 core 和 full 精确开放的工具
• 项目技能管理器 — 为受支持的 AI 客户端配置项目级技能，并提供内置的 unity-mcp-workflow 和 unity-ui-composition 指引
• MCP 设置 — 调整 execute_code 安全默认值，并在排查 MCP 连接或工具执行问题时启用详细的插件调试日志
• 不绑定厂商 — 适用于任何支持 MCP 的 AI 客户端：Claude Code、Cursor、Kimi Code、LM Studio、Windsurf、Codex、VS Code Copilot 等

execute_code：内存中的 C# 执行

execute_code 是 Funplay MCP for Unity 的核心。它允许 AI 编写 C# 代码片段，通过以 Roslyn 为先的内存流程进行编译，并在编辑器线程上运行代码——Agent 无需将任何项目文件写入磁盘，即可使用完整的 Unity Editor 和运行时 API。

• 编译不占用项目空间 — 代码片段首先使用 Unity 自带的 Roslyn csc 编译，同时保留内存编译／执行流程。不会在 Assets/ 下写入 .cs 文件，不会触发域重载，也不会触及代码片段本身操作以外的项目状态。
• 运行前确保编辑器就绪 — 每次调用都会刷新 AssetDatabase，并等待任何待处理的编译完成，然后再编译代码片段，因此外部文件编辑会自动生效，无需单独调用 request_recompile。
• 自动撤销 + 结构化日志（推荐模板） — 实现 IFunplayCommand 并使用注入的 ExecutionContext，使每个创建／修改／销毁的对象都参与编辑器撤销，并将变更记录返回给 Agent。

using UnityEngine;
using UnityEditor;
using Funplay.Editor.Tools.Helpers;
using Funplay.Editor.Tools.Scripting;

public class CommandScript : IFunplayCommand
{
    public void Execute(ExecutionContext ctx)
    {
        var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
        ctx.RegisterObjectCreation(go);          // auto-Undo + tracked
        ctx.Log("Created {0}", go.name);
        ctx.ReturnValue = GameObjectSerializer.Describe(go, includeComponents: false);
    }
}

响应包含 { logs, created, modified, destroyed, returnValue }，因此 Agent 无需重新查询场景，即可准确确认哪些内容发生了变化。

旧版模板（public static string Run()）仍受支持——适用于一次性检查代码片段，无需进行结构化跟踪的场景。

何时使用 execute_code，何时使用专用工具 — execute_code 适用于多步骤编排、新颖的读取需求，以及串联 5–10 次狭窄范围的工具调用比单个代码片段更繁琐的情况。对于单字段组件编辑、简单的选择更改，或现有工具已能覆盖的操作，优先使用专用工具——LLM 调用成本更低，也更容易验证。

与 Coplay 的比较

下表将本仓库与 GitHub 上公开文档描述的 Coplay 开源 unity-mcp 仓库行为进行了比较。

Coplay 栏目的来源：CoplayDev/unity-mcp

与 Unity AI Assistant 的比较

下表比较了此代码库与 Unity Technologies 官方 com.unity.ai.assistant 包（截至 2026-05 的版本为 v2.7.0-pre.2）。

如需了解这两种方案的详细比较，请参阅 Funplay Unity MCP 与 Unity AI Assistant 详细比较（中文）。

MCP 功能

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

• 工具 — full 配置共 185 个工具，core 配置包含 40 个专用工具
• 主要执行方式 — 使用 execute_code 进行丰富的 Editor/运行时编排
• 提示词 — 参数化工作流提示词：edit_prefab_safely、verify_compilation、enter_play_and_recover、wire_serialized_references、create_playable_prototype。项目可通过项目根目录中的 mcp-prompts/*.md 文件添加自定义提示词。
• 资源 — 项目上下文、场景摘要、选择状态、编译错误、控制台错误、MCP 交互历史，以及场景对象、组件和资源路径的资源模板

项目提示词

项目提示词文件采用简洁、无依赖的 front-matter 格式，后接工作流正文：

---
name: validate_activity
description: Open and validate a project activity.
arguments: activity_key(required), theme_id
---
Open activity {activity_key} with theme {theme_id}, then validate its runtime state.

名称和参数名称必须符合 [a-z][a-z0-9_-]{0,63}。prompts/get 会拒绝必填、未知及非字符串参数。未提供的可选占位符会替换为空字符串。定义会在 MCP 服务启动时缓存，因此修改提示词文件后，请重启服务或触发 Unity 域重新加载。

内置工具

版本 0.7.2 包含 43 个模块中的 185 个工具函数，其中 40 个高频工具默认开放。有关身份迁移、严格输入、连续拖动、自有资源清理、引用保留和证据复用，请参阅执行信任与验证。

📊 完整的 Profiler 工具参考、实现说明、已知限制和测试报告，请参阅 PROFILER_TOOLS.md。

有关端到端准备、只读审计、结构化查询、项目 TMP/Prefab/输入默认设置、捕获坐标映射、录制标记/关键帧，以及可恢复的预览会话，请参阅 可靠的 UI 工作流。两个内置的 Project Skills 都包含这些工作流；使用 Project Skills 更新现有安装。从 v0.6.9 开始，这些工具和技能更新均已包含在内。

录制 Game View 视频

使用 record_game_view（包含在 core 中），将 UI 动画、过渡和多步骤交互录制为简短的无声 MP4，以便查看。它使用 Unity 内置的 MediaEncoder；无需 Recorder 包或外部编码器。

1. 进入 Play Mode，等待重新加载恢复完成，并打开 Game 选项卡使其渲染。
2. 调用 record_game_view，参数为 {"action":"start","duration_seconds":10,"fps":15,"max_dimension":1280}。保存其 recording_id。
3. 录制期间执行交互。start 会立即返回，达到时长限制后会自动停止录制。
4. 使用 {"action":"status","recording_id":"<id>"} 轮询状态。若要提前结束，请使用 action:"stop"，然后持续轮询，直到完成最终处理。
5. 当 ready:true 时，将返回的 path 作为本地视频文件读取。视频字节不会嵌入 MCP 响应；远程客户端需要单独访问 Unity 机器上的文件。

片段会在 <UnityProject>/Library/FunplayMcp/Recordings/ 下使用唯一文件名，并一直保留，直到你将其删除。start 接受 1–120 秒的时长、1–60 FPS 的目标帧率，以及 128–1920 像素的最大尺寸；它会保持宽高比，不会放大，并使用偶数编码尺寸。状态包含实际帧数、经过时间、停止原因、文件大小和错误。轮询或停止时请传入录制 ID，以免误操作更新的片段。

目前支持处于 Play Mode 的 macOS 和 Windows Editor，且不包含音轨。它会捕获渲染后的 Game View（包括覆盖层 UI），不会重新渲染场景摄像机。录制期间请保持 Game 选项卡处于渲染状态，且不要调整其大小：隐藏或关闭选项卡，或更改其渲染分辨率，都会导致录制报错停止，而不是静默捕获过时或拉伸的帧。退出 Play Mode 会完成片段的最终处理；脚本/域重新加载会提前完成处理，并在编辑器会话中保留 interrupted 回执。仅使用 ready:true 的文件。较慢的帧会保留其实际时间戳，但录制会增加开销：这是视觉证据，不是帧级精准的性能分析。

添加自定义工具

使用简单的属性注释创建自己的工具：

using System.ComponentModel;

[ToolProvider("MyTools")]
public static class MyCustomTools
{
    [Description("Spawns enemies at random positions in the scene")]
    public static string SpawnEnemies(
        [ToolParam("Number of enemies to spawn", Required = true)] int count,
        [ToolParam("Prefab path in Assets")] string prefabPath)
    {
        // Your implementation here
        return $"Spawned {count} enemies";
    }
}

方法会自动被发现、转换为 snake_case（spawn_enemies），并通过 MCP 以 JSON Schema 定义的形式公开。

架构

MCP Server (HTTP JSON-RPC 2.0)
    └─ MCPRequestHandler (protocol handling)
        └─ MCPExecutionBridge
            └─ FunctionInvokerController (reflection-based invocation)
                └─ Tool Functions (185 built-in tools across 43 modules)

External AI Client → HTTP Request → MCPRequestHandler → MCPExecutionBridge → FunctionInvokerController → tool method

要求

• Unity 2022.3 或更高版本
• 带有 Newtonsoft.Json 的 .NET / Mono

贡献

欢迎贡献！提交 PR 前，请阅读贡献指南。

许可证

MIT — 可自由用于、修改、分发，并集成到商业或开源项目中。