Unity MCP Search

A Unity Editor package that exposes asset search, references, and dependency analysis as an MCP (Model Context Protocol) server, enabling AI coding assistants like Claude Code and OpenCode to query your Unity project's asset graph.

Architecture

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

The Python process acts as a thin MCP-to-HTTP bridge. The real work happens inside the Unity Editor on the main thread, using AssetDatabase and SearchService APIs.

Requirements

• Unity 2021.3 or later
• Python 3.10 or later

Installation

Option A: Unity Package Manager (Git URL)

1. Open Unity, go to Window > Package Manager
2. Click + > Add package from git URL...
3. Enter:

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

Option B: Git Submodule

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

Option C: Local Clone

Clone the repo into your project's Packages/ folder:

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

Setup

1. Setup Python Environment

Go to Tools > MCP Search > Setup Python Environment.

This will:

• Find a suitable Python 3.10+ interpreter on your system
• Create a virtual environment inside the package (MCP~/venv/)
• Install the Python dependencies (mcp, httpx)

2. Configure Your AI Client

Go to Tools > MCP Search > Copy MCP Config to copy the MCP server configuration JSON to your clipboard.

The config looks like this:

{
  "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"]
    }
  }
}

Paste it into your AI client's MCP settings:

• Claude Code: ~/.claude/settings.json
• OpenCode: ~/.config/opencode/config.json (under the mcp_servers section)

3. Verify

Go to Tools > MCP Search > Check Environment to verify everything is set up correctly. You should see:

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

Available MCP Tools

Once configured, your AI client can use the following tools:

search_assets

Search for assets using Unity Search query syntax.

search_assets(query="t:Material sky")

Supported filters:

• t:Type — filter by asset type (e.g. t:Texture, t:Prefab, t:Scene)
• l:label — filter by asset label
• ref:path — find assets referencing a given path
• dep:path — find assets that depend on a given path

Returns: path, name, type for each match.

get_asset_info

Get detailed info about a specific asset.

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

Returns: path, guid, type, size, sizeFormatted, dependencyCount, referenceCount, dependencies, references.

find_asset_references

Find all assets that reference the specified asset.

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

Returns a list of asset paths.

find_asset_dependencies

Find all dependencies of the specified asset.

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

Returns a list of asset paths.

find_unused_assets

Scan a directory for assets that are not referenced by anything in the project.

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

Automatically excludes:

• Resources/ folders (loaded at runtime by name)
• Build scenes
• Addressable asset entries
• StreamingAssets/
• Scripts and shaders
• Editor/ folders
• Packages/

Returns: path, size, sizeFormatted for each unused asset.

Unity Editor Menu

All menu items are under Tools > MCP Search:

Menu Item	Description
Start Server	Start the HTTP server (auto-starts on editor launch)
Stop Server	Stop the HTTP server
Setup Python Environment	Create venv and install dependencies
Check Environment	Verify all components are working
Copy MCP Config	Copy MCP server config JSON to clipboard
Server Status	Show current server status

How It Works

• The Unity HTTP server (McpHttpServer.cs) starts automatically when the editor opens via [InitializeOnLoad]. It listens on localhost:8090.
• HTTP requests from the Python bridge are queued and processed on Unity's main thread (required by AssetDatabase and SearchService APIs).
• The Python MCP server (MCP~/server.py) translates MCP tool calls into HTTP requests. The MCP~ directory is ignored by Unity's asset importer (directories ending with ~ are excluded).
• The Python venv lives inside the package at MCP~/venv/ and is excluded from version control via .gitignore.

Troubleshooting

"Cannot connect to Unity Editor"

• Make sure Unity Editor is open and focused (the HTTP server runs in the editor process)
• Check Tools > MCP Search > Server Status
• Try Tools > MCP Search > Stop Server, then Start Server

"Asset not found" errors

• Asset paths must use forward slashes and start with Assets/ (e.g. Assets/Sprites/hero.png)

Python setup fails

• Ensure Python 3.10+ is installed: python3 --version
• On macOS with Homebrew: brew install python@3.12
• On Windows: download from https://www.python.org/downloads/

Timeouts on large projects

• find_unused_assets on the root Assets/ directory may take a while on large projects. Use the directory parameter to narrow the scope, or extensions to filter by file type.

License

MIT