一、前置环境准备（新手必看：先装齐工具！）

1. 基础工具安装（分 Windows/macOS 说明）

工具	安装要求	新手操作要点
Unity 编辑器	推荐 2020.3 LTS/2022.3 LTS 版（从Unity 官网下载，选 “个人版”）	安装时务必勾选 “Git 支持”（如图 1：安装界面 “组件” 里找 “Git for Windows”/“Git for macOS”）
Python 环境	3.9~3.11 版本（Python 官网下载）	安装时必须勾选 “Add Python to PATH”（Windows 重点！如图 2），装完后打开 “命令提示符”/“终端”，输入python --version，能显示版本号就是装对了
Git CLI	（Windows：装 Python 时若没带 Git，从Git 官网下载；macOS：自带，无需额外装）	装完后打开 “命令提示符”/“终端”，输入git --version，显示版本号即成功
uv 包管理器	Python 的辅助工具，用于启动服务器	打开 “命令提示符”/“终端”，直接复制粘贴命令：Windows：pip install uv macOS：pip3 install uv （若提示 “pip 不是内部命令”，先重启电脑再试）
可选：Node.js	仅用 “Node.js 服务器” 时装，18 + 版本（Node 官网）	安装时勾选 “Add to PATH”，装完输入node --version验证

2. MCP 客户端（选一个就行！）

新手推荐用 Claude Desktop（官网下载）或 Cursor（官网下载），这两个支持自动配置，不用手动改太多设置。

二、核心组件安装（一步一操作，别跳步！）

（一）Unity 插件安装（二选一，推荐方案 1，更简单）

方案 1：Git URL 一键安装（新手优先）

1. 打开 Unity，进入任意项目（或新建一个空项目，名字随便取，比如 “MCPTest”）

1. 点击顶部菜单栏 Window → Package Manager（打开包管理器，如图 3）

1. 点击包管理器左上角的 “+” 号（如图 4），选择 “Add package from git URL...”

1. 复制下面任意一个地址，粘贴到输入框，点击 “Add”：

# 方案1（稳定版，推荐）

https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge

# 方案2（基础版，若方案1报错用这个）

https://github.com/Unity-Technologies/com.unity.mcp.git

1. 等待安装：Unity 右下角会显示 “Importing packages” 进度条，别关掉 Unity！

1. 安装成功判断：顶部菜单栏出现 Unity MCP 选项（如图 5），重启 Unity 后还在就是对的

方案 2：手动导入（方案 1 失败时用）

1. 打开 “命令提示符”/“终端”，复制命令并执行（克隆仓库）：

git clone https://gitcode.com/gh_mirrors/uni/Unity-MCP.git

• • 新手找不到克隆的文件？Windows：在 “此电脑→文档” 里；macOS：在 “访达→文稿” 里，文件夹名叫 “Unity-MCP”

1. 打开 Unity，点击顶部菜单栏 Assets → Import Package → Custom Package（如图 6）

1. 在弹出的窗口里，找到 “Unity-MCP” 文件夹，选择里面的UnityMCP.unitypackage文件，点击 “打开”

1. 弹出导入窗口，全选所有文件，点击 “Import”，等待完成后重启 Unity

（二）MCP 服务器配置（新手推荐 Python 服务器，更简单）

1. Python 服务器（主流方案，自动部署！）

• 不用手动下载！插件安装后，服务器已经自动放到你电脑里了：

• • Windows 路径：C:\Users\你的电脑用户名\AppData\Local\Programs\UnityMCP\UnityMcpServer\src

• • • 找不到 AppData？打开 “此电脑”，在地址栏输入%LocalAppData%\Programs\UnityMCP\UnityMcpServer\src，按回车

• • macOS 路径：/Users/你的电脑用户名/Library/Application Support/UnityMCP/UnityMcpServer/src

• • • 找不到 Library？按住 Option 键，点击访达 “前往”，会出现 Library 选项

• 手动启动验证（新手建议做，确认服务器能跑）：

1. 1. 打开 “命令提示符”/“终端”

1. 1. 复制下面的命令，把 “你的电脑用户名” 换成自己的（比如 Windows：cd C:\Users\ZhangSan\AppData\Local\Programs\UnityMCP\UnityMcpServer\src），粘贴执行：

# Windows

cd C:\Users\你的电脑用户名\AppData\Local\Programs\UnityMCP\UnityMcpServer\src

# macOS

cd /Users/你的电脑用户名/Library/Application Support/UnityMCP/UnityMcpServer/src

1. 1. 输入启动命令：uv run server.py

1. 1. 成功判断：终端显示 “Server running on port 8080”（没报错就是好的，别关掉这个终端窗口！）

2. Node.js 服务器（备选，新手慎选）

1. 打开 “命令提示符”/“终端”，克隆服务器代码：

git clone https://github.com/Unity-Technologies/unity-mcp-server.git

1. 进入文件夹并装依赖：

cd unity-mcp-server

npm install

npm run build

1. 启动：node build/index.js，显示 “Listening on port 8080” 即成功

三、连接配置与验证（新手关键步：让 AI 和 Unity 通上话！）

1. 客户端配置（推荐自动配置，不用改代码！）

方案 1：自动配置（新手必用）

1. 打开 Unity，点击顶部菜单栏 Unity MCP → Unity MCP Window（打开配置窗口，如图 7）

1. 窗口里有 “自动配置 Claude” 或 “自动配置 Cursor” 按钮，点击你用的客户端

1. 等待 30 秒左右，窗口右上角的指示灯变绿色（如图 8），就是连成功了！

方案 2：手动配置（自动配置失败时用，以 Claude 为例）

1. 找到 Claude 配置文件：

• • Windows：C:\Users\你的电脑用户名\AppData\Roaming\Anthropic\Claude\claude_desktop_config.json

• • macOS：/Users/你的电脑用户名/Library/Application Support/Anthropic/Claude/claude_desktop_config.json

1. 用记事本（Windows）或文本编辑（macOS）打开文件，在末尾的}前面，添加下面代码（注意前面加个逗号）：

,

"mcpServers": {

"UnityMCP": {

"command": "uv",

"args": ["run", "--directory", "C:\\Users\\你的电脑用户名\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src", "server.py"]

}

}

• • 新手注意：Windows 路径里的\要写两个（\\），macOS 写一个（/）

1. 保存文件，重启 Claude 和 Unity

2. 通信验证（新手必做：测试是否能用！）

1. 确保：Unity 开着、服务器终端开着（显示 8080 端口）、Claude/Cursor 开着

1. 在 AI 客户端（比如 Claude）输入测试指令，发送：帮我在Unity场景里创建一个名叫"CubeA"的立方体

1. 查看结果：

• • 成功：Unity 场景里出现灰色立方体，名字是 CubeA（如图 9）

• • 失败：打开 Unity 的 Unity MCP → Debug Window，看红色错误日志（常见原因：服务器没开、端口被占用）

1. 进阶测试（可选）：

• • 指令 1：获取Unity当前选中的物体名称（先在 Unity 点一个物体）

• • 指令 2：把CubeA的位置改成(1,2,3)

四、新手常见问题解决（按问题找答案！）

问题现象	解决步骤
Unity 装插件时提示 “Git not found”	1. 重新装 Git，勾选 “Add to PATH”；2. 重启 Unity；3. 还不行就重启电脑
输入uv run server.py提示 “uv 不是命令”	1. 打开终端，输入pip install uv（Windows）/pip3 install uv（macOS）；2. 重启终端
服务器提示 “port 8080 is in use”（端口被占）	1. 关闭可能占用 8080 的软件（如迅雷、浏览器插件）；2. 改服务器端口：打开 server.py，找到port=8080，改成 8081，保存后重启服务器
AI 发指令后 Unity 没反应	1. 检查服务器终端是否还开着；2. 检查 Unity 的 Debug Window 有没有红色日志；3. 重启 AI 客户端和 Unity
Python 安装后输入python --version报错	Windows：1. 打开 “控制面板→卸载程序”，卸载 Python；2. 重新安装，务必勾 “Add to PATH”；3. 重启命令提示符

五、新手操作核对表

• 装 Unity（勾 Git 支持）

• 装 Python（勾 PATH），验证python --version

• 装 uv，验证uv --version

• 装 AI 客户端（Claude/Cursor）

• Unity 装 MCP 插件，出现 “Unity MCP” 菜单

• 启动服务器，终端显示 8080 端口

• 自动配置 AI 客户端，指示灯变绿

• 发送指令创建 CubeA，Unity 成功生成

六、新手友好工具推荐

1. Git 可视化工具：代替命令行，新手好操作（Windows：TortoiseGit；macOS：SourceTree）

1. Python 环境管理：用 Anaconda（官网），避免版本冲突

1. 端口查看工具：Windows 用 “资源监视器→网络→侦听端口”，找 8080 对应的程序；macOS 用终端输入lsof -i :8080