Unity MCP安装指南：让AI控制Unity编辑器

背景

Unity开发中有很多重复性操作：创建GameObject、调整材质、管理场景层级……如果能用自然语言让AI帮你做这些事，效率会提升很多。

MCP for Unity 就是这样一个桥梁——它通过 MCP（Model Context Protocol）协议把 AI 助手（Claude Code、Cursor 等）和 Unity 编辑器连接起来，让 AI 可以直接操控你的 Unity 项目。

本文记录从零安装 Unity MCP 并跑通 Claude Code 连接的完整流程。

前置要求

Unity 2021.3 LTS+
Python 3.10+
uv（Python 包管理器，替代 pip）
Claude Code（或其他 MCP 客户端）

安装流程

第一步：安装 uv

uv 是一个极快的 Python 包管理器，Unity MCP 的 Python 服务器通过它来运行。

1	curl -LsSf https://astral.sh/uv/install.sh \| sh

安装完成后确认：

1	uv --version

macOS 用户如果遇到 command not found，需要把 ~/.local/bin 加入 PATH：
1
2
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

第二步：安装 Unity 包

在 Unity 编辑器中：Window > Package Manager > 左上角 + > Add package from git URL...

输入：

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

想用最新 beta 版本则用：

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

Unity 会自动拉取 Git 仓库并编译三个程序集：MCPForUnity.Editor、MCPForUnity.Runtime、MCPDynamic。

第三步：启动 MCP 服务器

Unity 中打开 Window > MCP for Unity
点击 Start Server
服务器会在 localhost:8080 启动（默认端口）
看到 🟢 “Connected ✓” 表示服务器已就绪

第四步：配置 Claude Code 连接

在 Unity 的 MCP 窗口中，从下拉菜单选择你的客户端并点击 Configure，或者手动配置。

HTTP 模式（推荐）

在项目根目录创建 .mcp.json：

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

也可以用命令行添加：

1	claude mcp add unityMCP --transport http --url http://localhost:8080/mcp

Stdio 模式

不需要在 Unity 中手动 Start Server，Claude Code 会自动启动 Python 进程：

1	claude mcp add unityMCP uvx --from mcpforunityserver mcp-for-unity --transport stdio

第五步：验证连接

重启 Claude Code，然后试试：

1	在场景中创建一个红色立方体

1	创建一个金属质感的金色材质，应用到一个新的球体上

如果 AI 能成功操作 Unity，说明连接已建立。

架构原理

理解架构有助于排查问题：

Claude Code
    │  HTTP / stdio
    ▼
Python MCP Server (FastMCP, 端口 8080)
    │  WebSocket + HTTP
    ▼
Unity Editor Plugin (C#)
    │  Unity Editor API
    ▼
Scene, Assets, Scripts

关键点：

Python 服务器是中间层，负责 MCP 协议转换，通过 WebSocket 连回 Unity 插件
Unity 插件通过反射扫描 [McpForUnityTool] 和 [McpForUnityResource] 特性，自动注册所有工具
调用链路：Claude Code → HTTP POST → Python 服务器 → WebSocket → Unity 插件 → 执行 Unity API → 结果原路返回

两种传输模式对比

模式	配置	特点
HTTP	`"type": "http", "url": "http://localhost:8080/mcp"`	多客户端共享，需在 Unity 中手动 Start Server
Stdio	`"command": "uvx", "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]`	单客户端独占，Claude Code 自动启动 Python 进程

HTTP 模式适合多个 AI 客户端同时连接同一个 Unity 实例；Stdio 模式更简单，适合单人工作流。

内置工具一览

安装后立即可用的部分工具：

类别	工具	说明
场景	`manage_scene`	创建/打开/保存场景，多场景编辑
对象	`manage_gameobject`	创建/修改/查找/删除 GameObject
组件	`manage_components`	添加/修改/获取组件
材质	`manage_material`	创建和修改材质
脚本	`create_script` / `manage_script`	创建和修改 C# 脚本
资产	`manage_asset`	管理项目资产
编辑器	`manage_editor`	播放/暂停/停止，撤销/重做
控制台	`read_console`	读取 Unity 日志
截图	`screenshot_camera`	从摄像机截图
批量	`batch_execute`	批量执行操作，速度提升 10-100x

性能提示：需要连续执行多个操作时，优先使用 batch_execute，比逐个调用快得多。