Unity Editor MCP

English | 日本語

Overview

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

Related Docs

• Video Capture Feature Plan: docs/video-capture-plan.md
• Planned: C# Language Server (self-contained) RFC: docs/RFCs/0001-csharp-lsp.md

C# Editing Policy (Important)

• All C# symbol/search/structured edits are performed via a self-contained C# Language Server (LSP) bundled in this repo; no Unity communication is involved.
• Existing script_* tools call the LSP under the hood, so edits are robust to Unity compilation/domain reload.
• Risky line-based patch/pattern replace tools were removed.

For Contributors

Developer note: the LSP is self-contained and auto-provisioned by the MCP server (fixed-version by tag). No .NET SDK is required for end users.

Common usage (MCP tools)

• Symbols: script_symbol_find { "name": "ClassName", "kind": "class" }
• References: script_refs_find { "name": "MethodName" }
• Replace body (preflight→apply):
  • script_edit_structured { "operation": "replace_body", "path": "Packages/.../File.cs", "symbolName": "Class/Method", "newText": "{ /* ... */ }", "preview": true }
  • then set "preview": false to apply if errors are empty
• Insert after class:
  • script_edit_structured { "operation": "insert_after", "path": "...", "symbolName": "ClassName", "kind": "class", "newText": "\nprivate void X(){}\n", "preview": false }

Run AssetDatabase.Refresh in Unity manually only when needed.

Performance mode (default)

• The server runs a persistent LSP process by default to avoid cold starts.
• To opt-out (one-shot per request), set ROSLYN_CLI_MODE=oneshot (or off).

LLM Optimization Principles

• Prefer small responses: enable paging and set conservative limits.
• Use snippets: avoid full file reads; favor short context windows (1–2 lines).
• Scope aggressively: restrict by Assets/ or Packages/, kind, and exact names.
• Favor summaries: rely on tool-side summarized payloads where available.
• Avoid previews unless necessary: apply directly when safe to reduce payload.
• Keep image/video resolutions minimal and avoid base64 unless immediately analyzed.

Suggested caps

• Search: pageSize≤20, maxBytes≤64KB, snippetContext=1–2, maxMatchesPerFile≤5.
• Hierarchy: nameOnly=true, maxObjects 100–500 (details: 10–50).
• Script read: 30–40 lines around the target; set maxBytes.
• Structured edits: responses are summarized (errors ≤30, message ≤200 chars; large text ≤1000 chars).

Safe Structured Edit Playbook

1. Locate symbols: script_symbols_get or script_symbol_find (prefer kind and exact).
   • Use project-relative paths under Assets/ or Packages/ only.
   • Use results’ container to build namePath like Outer/Nested/Member.
2. Inspect minimal code: script_read with 30–40 lines around the symbol.