使用说明

本地MCP服务器

Unity Editor的MCP（模型上下文协议）服务器，使Claude等AI助手能够通过标准化工具与Unity项目进行交互。

特性

40+内置工具 用于资产管理、场景操作、组件检查等
基于事件的编译等待 -无轮询，编译完成时立即通知
资产缓存 -重复查询速度提高10-50倍
可扩展 -在项目中添加具有简单属性的自定义工具
自主发展 -编写、修改和删除带有编译反馈的脚本

快速入门（5分钟）

步骤1：安装软件包

选项A：通过Unity软件包管理器（推荐）

打开Unity项目
首选 Window > Package Manager
点击 + 左上角的按钮
选择 Add package from git URL...

粘贴此URL并单击“添加”：

https://github.com/caner-cc/local-mcp-server.git

选项B：直接编辑manifest.json

打开 YourProject/Packages/manifest.json 并将此行添加到 dependencies 章节：

{
  "dependencies": {
    "com.localmcp.server": "https://github.com/caner-cc/local-mcp-server.git",
    ...
  }
}

保存文件。Unity将自动下载并安装该软件包。

步骤2：启用MCP服务器

在Unity中，转到 Tools > MCP > Enable MCP Server
您应该看到一条控制台消息： [MCP] Server started on port 8090

服务器现在正在运行并侦听连接。

步骤3：连接克劳德代码

选项A：复制mcp.json文件（推荐）

复制 mcp.json 从包文件夹到Unity项目根目录：

Packages/com.localmcp.server/mcp.json  →  YourProject/mcp.json

Claude Code将在您打开项目时自动发现服务器。

选项B：手动注册

在项目目录中打开一个终端并运行：

claude mcp add --transport http unity http://localhost:8090/mcp -s project

步骤4：验证它是否有效

启动Claude Code会话并尝试：

"Use the editor_state tool to check Unity's current state"

Claude应该能够查询Unity，并告诉你它是否正在播放、暂停、当前场景名称等。

你能用它做什么？

连接后，Claude可以：

查找和检查资产 -“在资源/数据中查找所有ScriptableObjects”
创建游戏对象 -在原点创建一个名为“GameManager”的空游戏对象
添加组件 -“向Player对象添加刚体”
编写脚本 -“创建最大健康值为100的PlayerHealth.cs脚本”
控制编辑器 -“进入播放模式”/“停止播放”
读取控制台日志 -“显示最后10条错误消息”
浏览场景 -“在场景视图中框定主摄像头”

内置工具参考

资产运营

工具	说明
`asset_find`	按类型/名称/文件夹查找资产（缓存，快速）
`asset_info`	获取资产属性和引用
`asset_create`	创建新的ScriptableObjects
`asset_modify`	修改资产属性
`asset_delete`	删除资产
`asset_move`	移动/重命名资源
`asset_dependencies`	显示资产依赖关系
`prefab_instantiate`	在场景中实例化预制件

场景操作

工具	说明
`scene_info`	当前场景详细信息
`scene_load`	加载场景
`scene_save`	保存当前场景
`gameobject_create`	创建游戏对象
`gameobject_find`	在层次结构中查找对象
`gameobject_modify`	修改变换/属性
`gameobject_delete`	删除游戏对象

组件操作

工具	说明
`component_add`	将组件添加到游戏对象
`component_remove`	移除组件
`component_inspect`	查看组件属性
`component_set`	设置组件属性值

编辑器控件

工具	说明
`editor_control`	播放/暂停/停止
`editor_state`	获取编辑器状态
`sceneview_lookat`	移动场景摄影机
`sceneview_frame`	视图中的框架对象
`ping_asset`	突出显示项目中的资产
`open_script`	在IDE中打开脚本

开发工具

工具	说明
`write_script`	创建C#脚本（等待编译）
`modify_script`	编辑现有脚本
`delete_script`	删除脚本
`wait_for_compilation`	等待Unity完成编译
`ensure_ready`	封锁，直到Unity准备就绪
`compile_errors`	获取当前编译错误
`console_read`	读取Unity控制台日志
`console_clear`	清除控制台
`mcp_health`	服务器诊断

创建自定义工具

通过创建类将自定义工具添加到项目中 [MCPTool] 属性：

using Newtonsoft.Json.Linq;
using LocalMCP;

public static class MyProjectTools
{
    [MCPTool("my_tool", "Description of what the tool does")]
    [MCPParam("myParam", "string", "Description of parameter")]
    [MCPParam("optionalParam", "integer", "Optional parameter", false)]
    public static object MyTool(JObject args)
    {
        var myParam = args["myParam"]?.ToString();
        var optionalParam = args["optionalParam"]?.ToObject<int>() ?? 10;

        // Do something...

        return new { success = true, result = "..." };
    }
}

工具是通过反射自动发现的。您的程序集必须引用 LocalMCP.Editor.

导入样本

打开包管理器
查找“本地MCP服务器”
展开“示例”
点击“自定义工具示例”旁边的“导入”

配置

MCP控制面板

通过以下方式访问 Tools > MCP > Control Panel:

启用/禁用服务器
查看连接状态
监控工具调用
清除请求队列

编辑器序言键

密钥	默认值	描述
`LocalMCP_Enabled`	false	服务器启用状态
`LocalMCP_Port`	8090	服务器端口
`LocalMCP_ShowToolbar`	false	显示场景视图工具栏

故障排除

服务器无法启动

检查端口8090/8091是否已在使用中
尝试 Tools > MCP > Force Stop MCP (Emergency) 然后重新启用

工具未出现

跑 Tools > MCP > Refresh Tool Registry
检查Console中的编译错误

克劳德无法连接

确保服务器已启用（检查 Tools > MCP > Control Panel)
验证端口： curl http://localhost:8090/heartbeat
重新注册： claude mcp remove unity -s project 然后重新添加

WSL2无法连接

无法从WSL2访问Windows localhost。使用PowerShell作为桥梁：

powershell.exe -Command "Invoke-WebRequest -Uri 'http://localhost:8090/mcp' -Method POST -ContentType 'application/json' -Body '{...}' -TimeoutSec 30 -UseBasicParsing | Select-Object -ExpandProperty Content"

需求

Unity 2021.3或更高版本
Newtonsoft。Json（作为依赖项自动安装）

许可证

MIT许可证-有关详细信息，请参阅许可证文件。