UnityIndexMCP

UnityIndexMCP is a local, read-only Model Context Protocol (MCP) server for Unity projects. It gives AI coding clients ranked code search, C# symbols, references, outlines, related Unity assets, and bounded snippets without sending project files to a hosted indexing service.

The lexical index supports C#, UXML, USS, shaders, assembly definitions, JSON, YAML, project settings, and package manifests. An optional .NET/Roslyn worker adds accurate C# symbol, reference, and implementation queries when Unity has generated a solution.

Features

• Local SQLite/FTS5 index with live file watching
• Unity-aware discovery for Assets, Packages, and ProjectSettings
• Roslyn semantic analysis with graceful lexical fallback
• Bounded, ranked results designed to reduce agent context usage
• Multiple configurable Unity project roots
• Stdio transport with no network listener, telemetry, or write tools
• Windows, macOS, and Linux support wherever Node.js and .NET are available

Requirements

• Node.js 22 or newer
• npm 9 or newer
• .NET 8 SDK for full semantic mode (optional, recommended)
• A Unity project with Assets/ and ProjectSettings/
• A Unity-generated .sln or .slnx for full semantic mode

Unity 6 is the primary target. The lexical index can also work with older Unity projects that use the same project layout; Roslyn compatibility depends on the generated solution and installed SDKs.

Install

Clone and build the server in a tools directory outside the Unity project:

git clone https://github.com/zloybest/UnityIndexMCP.git
cd UnityIndexMCP
npm ci
npm run build
npm run build:worker

npm run build:worker is optional. Without it, UnityIndexMCP continues in degraded semantic mode and all lexical tools remain available.

On Windows, stop connected MCP clients before rebuilding an existing worker; a running dotnet process locks dist/worker/UnityCodeIndex.Worker.dll.

Configure a Unity project

Copy unity-index-mcp.config.example.json to the root of the Unity project as unity-index-mcp.config.json. The portable minimum is:

{
  "projectRoots": ["."]
}

Relative paths are resolved from the configuration file. If solutionPath is omitted, the server looks for a .sln or .slnx in the first project root. Each Unity project should normally use its own config and index database.

You may instead omit the config and set UNITY_PROJECT_ROOT to the Unity project directory. Use UNITY_INDEX_CONFIG when the MCP client starts outside the project directory:

UNITY_INDEX_CONFIG=/absolute/path/to/MyGame/unity-index-mcp.config.json

Configuration reference

Setting	Default	Meaning
projectRoots	required	Allowed Unity project directories
solutionPath	auto-detected	Unity-generated .sln or .slnx
indexDbPath	.cache/unity-index/index.sqlite	SQLite index, relative to the first project root
semantic.enabled	true	Enable the optional Roslyn worker
semantic.workerPath	./dist/worker/UnityCodeIndex.Worker.dll	Worker path, relative to the UnityIndexMCP install
files.includePackages	true	Index embedded/local package source
files.includePackageCache	false	Index Unity's generated package cache
watch.enabled	true	Incrementally index file changes

See the example config for search, exclusions, logging, and other settings.

Connect an MCP client

Use absolute paths in client configuration. Keep the server installation path and Unity project config path separate.

Codex / ChatGPT desktop app

The quickest Codex CLI setup is:

codex mcp add unity-index \
  --env UNITY_INDEX_CONFIG=/absolute/path/to/MyGame/unity-index-mcp.config.json \
  -- node /absolute/path/to/UnityIndexMCP/dist/mcp/server.js

Or add the contents of codex-mcp-config.example.toml to ~/.codex/config.toml (or .codex/config.toml in a trusted project), then restart the client. The ChatGPT desktop app, Codex CLI, and Codex IDE extension share that configuration; see the official OpenAI MCP setup documentation for current client details.

Claude Desktop and other JSON-configured clients

{
  "mcpServers": {
    "unity-index": {
      "command": "node",
      "args": ["/absolute/path/to/UnityIndexMCP/dist/mcp/server.js"],
      "env": {
        "UNITY_INDEX_CONFIG": "/absolute/path/to/MyGame/unity-index-mcp.config.json"
      }
    }
  }
}

Restart the MCP client after changing its configuration. Call index_status first; initial indexing runs in the background.

Tools

Tool	Purpose
index_status	Index health, freshness, and semantic mode
project_overview	Project statistics, assemblies, and notable files
refresh_index	Full or incremental reindex
search_text	Ranked full-text search across supported files
find_symbol	C# declarations by name
get_file_outline	Compact type/member structure
read_snippet	Bounded source range within configured roots
find_references	C# references with Roslyn or lexical fallback
find_implementations	Implementations and derived types
get_related_files	Related code, UXML, USS, and configuration files
find_examples	Similar patterns and implementations
impact_analysis	Likely minimal file set for a described change

AGENT_INSTRUCTIONS.md contains a reusable workflow prompt for clients that do not consume the server's MCP instructions.

Semantic modes

Mode	Behavior
full	Roslyn loaded the Unity solution; semantic references and implementations are available
degraded	The worker or solution is unavailable; lexical search, outlines, and heuristics remain available
off	Semantic indexing is disabled in configuration

If the mode remains degraded, open the Unity project once, confirm its solution exists, build the worker, and verify solutionPath if auto-detection is not sufficient.

Updating without breaking existing projects

The public product and solution are named UnityIndexMCP, but compatibility identifiers remain unchanged:

• npm package and executable: unity-index-mcp
• MCP server/config key: unity-index
• config files: unity-index-mcp.config.json and .unity-index-mcp.json
• environment variables: UNITY_INDEX_CONFIG and UNITY_PROJECT_ROOT
• worker assembly: UnityCodeIndex.Worker.dll

Existing client configurations that point at a checkout directory named KebabIndex continue to work because the local directory is not moved automatically. To update safely, stop MCP clients, pull changes, run npm ci, npm run build, and optionally npm run build:worker, then restart the clients. Existing per-project configs and SQLite indexes do not need migration.

Development

npm ci
npm test -- --runInBand
npm run build
dotnet build UnityIndexMCP.sln -c Release

Integration tests use the repository's sample Unity project and do not require a Unity installation. See CONTRIBUTING.md before submitting a change.

Security and privacy

UnityIndexMCP exposes only local stdio, has no write tools, makes no cloud calls, and restricts file reads to configured roots. The index stores source-derived text locally in the configured SQLite database, so exclude that database from source control and protect it like source code. See SECURITY.md for reporting vulnerabilities.

Limitations

• Full semantic analysis requires a Unity-generated solution and the .NET worker.
• Scene and prefab YAML are lexically searchable but serialized object references are not semantically linked.
• UTF-8 is expected; UTF-16 and unusual encodings may not index correctly.
• Large projects may take several minutes to build their first index.
• Multiple roots share one database; identical root-relative paths can be ambiguous in tool output.

License

MIT. Unity is a trademark of Unity Technologies. This project is independent and is not affiliated with or endorsed by Unity Technologies.