Unity MCP Search

Unity MCP搜索

Unity Editor包，将资产搜索、引用和依赖关系分析作为 MCP（模型上下文协议） 服务器，使Claude Code和OpenCode等AI编码助手能够查询Unity项目的资产图。

建筑

AI Client (Claude Code / OpenCode / ...)
    | MCP Protocol (stdio)
    v
Python MCP Server (server.py)
    | HTTP (localhost:8090)
    v
Unity Editor HTTP Server (McpHttpServer.cs)
    |
    v
Unity AssetDatabase & SearchService APIs

Python进程充当一个从MCP到HTTP的瘦网桥。真正的工作发生在Unity编辑器的主线程中，使用 AssetDatabase 和 SearchService API。

需求

• 统一 2021.3或更晚
• python 3.10或更高版本

安装

选项A:Unity包管理器（Git URL）

1. 打开Unity，转到 窗口>包管理器
2. 点击 + > 从git URL添加包。。。
3. 输入：

   https://github.com/StromKuo/Unity-MCP-Search.git

选项B:Git子模块

git submodule add https://github.com/StromKuo/Unity-MCP-Search.git Packages/com.strodio.unity-mcp-search

选项C：本地克隆

将仓库克隆到您的项目中 Packages/ 文件夹：

cd YourProject/Packages
git clone https://github.com/StromKuo/Unity-MCP-Search.git com.strodio.unity-mcp-search

设置

1.设置Python环境

首选 工具>MCP搜索>设置Python环境.

这将：

• 在您的系统上找到合适的Python 3.10+解释器
• 在包内创建虚拟环境(MCP~/venv/)
• 安装Python依赖项(mcp, httpx)

2.配置您的AI客户端

首选 工具>MCP搜索>复制MCP配置 将MCP服务器配置JSON复制到剪贴板。

配置如下：

{
  "mcpServers": {
    "unity-search": {
      "command": "/path/to/Packages/com.strodio.unity-mcp-search/MCP~/venv/bin/python",
      "args": ["/path/to/Packages/com.strodio.unity-mcp-search/MCP~/server.py"]
    }
  }
}

将其粘贴到AI客户端的MCP设置中：

• 克劳德代码: ~/.claude/settings.json
• OpenCode: ~/.config/opencode/config.json （根据 mcp_servers 部分）

3.验证

首选 工具>MCP搜索>检查环境 验证所有设置是否正确。您应该看到：

System Python 3.10+:  OK
Virtual Env:          OK
Dependencies:         OK
HTTP Server:          Running (port 8090)

可用的MCP工具

配置后，您的AI客户端可以使用以下工具：

search_assets

使用搜索资产 Unity搜索 查询语法。

search_assets(query="t:Material sky")

支持的筛选器：

• t:Type --按资产类型筛选（例如。 t:Texture, t:Prefab, t:Scene)
• l:label --按资产标签筛选
• ref:path --查找引用给定路径的资产
• dep:path --查找依赖于给定路径的资产

退货： path, name, type 每场比赛。

get_asset_info

获取特定资产的详细信息。

get_asset_info(asset_path="Assets/Materials/Default.mat")

退货： path, guid, type, size, sizeFormatted, dependencyCount, referenceCount, dependencies, references.

find_asset_references

查找引用指定资产的所有资产。

find_asset_references(asset_path="Assets/Sprites/hero.png")

返回资产路径列表。

find_asset_dependencies

查找指定资产的所有依赖关系。

find_asset_dependencies(asset_path="Assets/Prefabs/Enemy.prefab", recursive=True)

返回资产路径列表。

find_unused_assets

扫描目录中未被项目中任何内容引用的资产。

find_unused_assets(directory="Assets/Art", extensions="png,jpg,mat")

自动排除：

• Resources/ 文件夹（在运行时按名称加载）
• 构建场景
• 可寻址资产条目
• StreamingAssets/
• 脚本和着色器
• Editor/ 文件夹
• Packages/

退货： path, size, sizeFormatted 对于每一项未使用的资产。

Unity编辑器菜单

所有菜单项都在下面 工具>MCP搜索:

运作原理

• 这 Unity HTTP服务器 (McpHttpServer.cs)当编辑器通过打开时自动启动 [InitializeOnLoad].它在听 localhost:8090.
• 来自Python桥的HTTP请求在Unity的主线程上排队和处理（需要 AssetDatabase 和 SearchService API）。
• 这 Python MCP服务器 (MCP~/server.py)将MCP工具调用转换为HTTP请求。这 MCP~ Unity的资产导入程序忽略了该目录（以结尾的目录 ~ 被排除在外）。
• Python venv位于包内 MCP~/venv/ 并且通过以下方式被排除在版本控制之外 .gitignore.

故障排除

“无法连接到Unity编辑器”

• 确保Unity编辑器打开并聚焦（HTTP服务器在编辑器进程中运行）
• 检查 工具>MCP搜索>服务器状态
• 尝试 工具>MCP搜索>停止服务器那么 启动服务器

“未找到资产”错误

• 资产路径必须使用正斜杠并以开头 Assets/ （例如。 Assets/Sprites/hero.png)

Python安装失败

• 确保已安装Python 3.10+： python3 --version
• 在macOS上使用Homebrew： brew install python@3.12
• 在Windows上：从下载https://www.python.org/downloads/

大型项目的超时

• find_unused_assets 根上 Assets/ 对于大型项目，目录可能需要一段时间。使用 directory 参数以缩小范围，或 extensions 按文件类型过滤。

许可证

麻省理工学院