unity-mcp-server

Unity MCP Server

[!WARNING] This repository is deprecated. Development has moved to akiojin/unity-cli. This repository will no longer receive updates. Please migrate to the successor project.

English | 日本語

Overview

Unity MCP Server lets LLM-based clients automate the Unity Editor. It focuses on reliable, scriptable workflows with a simple interface and zero or low-configuration setup.

What It Can Do

• Editor automation: Create/modify scenes, GameObjects, components, prefabs, materials
• UI automation: Locate and interact with UI, validate UI state
• Input simulation: Keyboard/mouse/gamepad/touch for playmode testing (Input System only)
• Visual capture: Deterministic screenshots from Game/Scene/Explorer/Window views
• Code base awareness: Safe structured edits and accurate symbol/search powered by bundled C# LSP (no .sln file required)
• Project control: Read/update project/editor settings; read logs, monitor compilation
• Addressables management: Register/organize assets, manage groups, build automation

Performance

Code index tools outperform standard file operations:

Operation	Code Index Tool	Standard Tool	Advantage
Symbol lookup	find_symbol	grep	Instant vs 350ms
Reference search	find_refs	grep	Structured results
Code search	search	grep	3-5x smaller responses

Key benefits:

• 128,040 files indexed with 100% coverage
• Non-blocking background index builds (Worker Threads)
• LLM-optimized output with pagination and size limits

For detailed benchmarks, see docs/benchmark-results-2025-12-13.md

Requirements

• Unity 2020.3 LTS or newer
• Node.js 18.x / 20.x / 22.x / 24.x LTS (25+ not supported)
• Claude Desktop or another MCP-compatible client

Installation

Unity Package

Package Manager → Add from git URL:

https://github.com/akiojin/unity-mcp-server.git?path=UnityMCPServer/Packages/unity-mcp-server

Or via OpenUPM:

openupm add com.akiojin.unity-mcp-server

MCP Client Configuration

Configure your MCP client (Claude Desktop example):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity-mcp-server": {
      "command": "npx",
      "args": ["@akiojin/unity-mcp-server@latest"]
    }
  }
}

HTTP Mode (for HTTP-only networks)

npx @akiojin/unity-mcp-server --http 6401 --no-telemetry
curl http://localhost:6401/healthz

Quick Start

1. Install the Unity package (Git URL or OpenUPM)
2. Configure your MCP client with the JSON above
3. Open your Unity project (package starts TCP listener on port 6400)
4. Launch your MCP client (it connects to the Node server)
5. Test the connection with ping

Tip: npx @akiojin/unity-mcp-server@latest downloads and runs the latest build without cloning.

Architecture

┌────────────────┐        JSON-RPC (MCP)        ┌──────────────────────┐
│  MCP Client    │ ───────────────────────────▶ │  Node MCP Server     │
│ (Claude/Codex/ │ ◀─────────────────────────── │ (@akiojin/unity-     │
│   Cursor …)    │        tool responses        │ mcp-server)          │
└────────────────┘                              └──────────┬───────────┘
                                                         TCP│6400
                                                            ▼
                                                   ┌───────────────────┐
                                                   │  Unity Editor     │
                                                   │  (Package opens   │
                                                   │   TCP listener)   │
                                                   └───────────────────┘

Configuration

Configuration is optional; defaults work without any config file.

Node-side configuration uses environment variables only, and Unity-side host/port lives in Project Settings.

See docs/configuration.md.

Tools

Unity MCP Server ships 100+ tools. Use the search_tools meta-tool to discover the right tool quickly.

For clients with strict tool-count limits, you can filter exposed tools by category:

export UNITY_MCP_TOOL_INCLUDE_CATEGORIES=system,scene,gameobject,analysis,script
export UNITY_MCP_TOOL_EXCLUDE_CATEGORIES=ui,input,addressables,video,screenshot,profiler

See docs/tools.md for discovery tips and the recommended Code Index workflow.

Note: find_refs supports paging via startAfter and returns cursor when results are truncated.

Claude Code Skills