Unity MCP Server

什么是 Unity MCP Server？

Unity MCP Server（MCP for Unity）是一个免费、采用 MIT 许可的 unity mcp 桥接工具，让 Claude、Cursor、VS Code、Codex 等 AI 助手可以直接操控 Unity Editor：管理资源、搭建场景、编辑 C# 脚本、运行测试。

该项目由 CoplayDev 维护，Aura 赞助。它最初是 justinpbarnett/unity-mcp，现在这个地址会跳转到 CoplayDev/unity-mcp。这是社区项目，与 Unity Technologies 没有关联。README 称它提供 50 个精简的 MCP 工具入口，任何 MCP 客户端都能用。

如何使用 Unity MCP Server？

前提条件： Unity 2021.3 LTS 至 6.x；Python 3.10+ 和 uv；PATH 中有 git（用 Git URL 安装时需要）；一个 MCP 客户端。核心工具不需要 API Key。

1. 安装 Unity 包。 在 Unity 中打开 Window → Package Manager，点击 +，选择“Add package from git URL...”，粘贴：

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

也可以通过 OpenUPM 或 Unity Asset Store 安装：

openupm add com.coplaydev.unity-mcp

2. 运行设置向导。 导入后会弹出向导，先检查 Python 和 uv，再列出本机检测到的 MCP 客户端。选中需要的客户端，点击 Configure Selected。之后也可以从 Window → MCP for Unity → Configure All Detected Clients 重新配置，重复运行不会出问题。
3. 输入提示词。 比如“Create a cube at the origin and add a Rigidbody.”。全部连通后，状态面板会显示 Connected。

unity mcp server 默认通过 HTTP 运行在 localhost:8080，也可以改用 stdio。

Claude Code

Claude Code 会被自动配置为 HTTP 连接。如需手动添加：

claude mcp add --transport http UnityMCP http://localhost:8080/mcp

如果在 MCP for Unity 窗口里切换了 HTTP 和 stdio，需要重启 Claude Code。

Claude Desktop

Claude Desktop 只支持 stdio。即使全局选择了 HTTP，配置器也会为它使用 stdio。macOS / Linux 的手动配置：

{
  "mcpServers": {
    "unityMCP": {
      "command": "uvx",
      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
    }
  }
}

在 Windows 上，请把 command 设为 uvx.exe 的完整路径（例如 C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe）。

Cursor

自动配置会写好配置项，之后还要在 Cursor Settings → MCP 中启用 unityMCP 服务器。手动配置：

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

VS Code

VS Code 使用 servers 而不是 mcpServers：

{
  "servers": {
    "unityMCP": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Codex 和 Windsurf

项目的客户端对照表把这两者列为 HTTP 客户端。运行配置器后，它们会自动连接。

Unity MCP Server 的主要功能

• 用自然语言控制 Unity Editor：场景、GameObject、组件、预制体、材质和资源
• 创建和编辑 C# 脚本，可选 Roslyn 脚本校验
• 在对话中运行测试、做性能分析、触发构建
• 工具分组（core、animation、ui、vfx、testing、probuilder、profiling、docs、asset_gen 等）。默认只启用 core，提示词因此更精简
• 一键配置 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Cline、Codex、Gemini CLI 等客户端
• 可在多个 Unity Editor 实例间路由，也可使用带认证的远程托管服务器
• 支持 Unity 2021.3 LTS 至 6.x；免费，MIT 许可

Unity MCP Server 工具

• 场景与对象（core）： manage_scene、manage_gameobject、find_gameobjects、manage_components、manage_prefabs、manage_camera、manage_physics 和 manage_material 用于创建和编辑场景内容。
• 脚本（core）： create_script、apply_text_edits、script_apply_edits、validate_script、find_in_file 和 delete_script 让模型安全地编写和修补 C# 代码。
• 编辑器与项目（core）： manage_editor、manage_asset、manage_packages、manage_build、execute_menu_item、read_console、refresh_unity，以及可在一次调用中执行多条命令的 batch_execute。
• 可选分组： run_tests 和 get_test_job（testing）、manage_shader 和 manage_vfx（vfx）、manage_ui、manage_animation、manage_profiler、manage_probuilder，以及 generate_model、generate_image 等 asset_gen 工具。这些工具需要你自己的服务商密钥。
• 元工具： manage_tools 可按会话启用或关闭分组，例如 manage_tools(action="activate", group="vfx")。set_active_instance 用于选择要操作的 Editor。

Unity MCP Server 的使用场景

• 用描述的方式搭关卡原型：“Create a red, blue, and yellow cube in the current scene.”
• 快速做玩法原型：“Build a simple player controller with WASD movement and a double-jump.”
• 审查代码：“List every script in Assets/Scripts and tell me which ones reference Rigidbody.”
• 更快修错：让助手读取控制台、修补脚本，再刷新 Unity。
• 启用 testing 分组后，在同一个对话里运行测试并修复失败用例。
• 不离开 IDE 就能切换构建平台或启动构建。

Unity MCP Server 与替代方案对比

• Unity 官方 MCP 服务器： Unity 在 Unity AI beta 的 AI Assistant 包中提供了自己的 MCP 服务器。它需要 Unity 6 或更高版本、连接到 Unity Cloud 的项目，以及 Unity AI 工具的试用或订阅（Unity 博客）。MCP for Unity 免费、开源，并支持更早的 LTS 版本。
• 其他引擎： Godot 请看 Godot MCP Server，3D 资源制作请看 Blender MCP Server。MCP for Unity 的 blender_bridge 工具可以连接已安装 BlenderMCP 插件并正在运行的 Blender。

Unity MCP Server 常见问题排查

• Package Manager 提示“Error when executing git command”： 用 Git URL 安装需要 PATH 中有 git。请安装 Git，或改用 OpenUPM 或 Asset Store。
• 服务器无法启动： 确认终端中 uv --version 能正常运行，再查看 MCP for Unity 日志。
• 客户端连不上： 确认 HTTP 服务器正运行在 localhost:8080，并且客户端配置中的 URL 与之一致。Cursor 还需要在 MCP 设置中启用该服务器。8080 端口可能与其他服务冲突（例如 Tailscale），可以在 MCP for Unity 设置中修改端口。
• macOS 上提示“Claude Not Found”： 从 Finder 或 Hub 启动的 Unity 可能不会继承 shell 的 PATH。请从终端启动 Hub，或在 MCP for Unity 窗口中使用“Choose Claude Install Location”。
• Unity 6.3+ 搭配 Unity AI Assistant 包时出现 System.Collections.Immutable 冲突： 项目文档建议把 System.Collections.Immutable v9.0.0 作为 DLL 放到 Assets/Plugins/。