UnityCliRunner

A native Model Context Protocol (MCP) server that connects AI coding agents (Antigravity, Claude Code, Cursor, VS Code) directly with the Unity Editor.

By communicating with a running Unity Editor (or a headless background instance) via loopback TCP sockets and exposing standard JSON-RPC stdio MCP tools, UnityCliRunner enables sub-second compilation feedback, instant test execution, dynamic C# evaluation, and static method invocations without shell quoting issues or slow batchmode restarts.

---

Overview & Key Capabilities

UnityCliRunner provides 6 core MCP tools:

1. unity_status: Inspects Editor connection state (Ready, Not Running, Compiling, or Running Unreachable).
2. unity_refresh: Triggers AssetDatabase.Refresh() and returns compiler diagnostics.
3. unity_recompile: Cleans compiler cache and forces a full rebuild of script assemblies.
4. unity_run_tests: Runs EditMode and/or PlayMode unit and integration tests with granular filtering by name (filter) and category (category).
5. unity_execute_method: Executes static C# methods (Namespace.Class.Method) with typed arguments and returns formatted outputs and console logs.
6. unity_eval: Evaluates live C# expressions, statements, or multiline blocks dynamically in-memory without domain reloads.
7. unity_stop: Safely stops the running Unity background instance.

---

MCP Tools at a Glance

Tool	Parameters	Description
unity_status	none	Checks Editor state (Ready, Not Running, etc.).
unity_refresh	none	Triggers AssetDatabase.Refresh() and returns compilation diagnostics.
unity_recompile	none	Forces a full C# recompilation (clears build cache) and returns compiler diagnostics.
unity_run_tests	filter, category, mode (all, editmode, playmode)	Runs tests and reports pass/fail/skip counts and failed stack traces.
unity_execute_method	methodName, args (array)	Executes static C# method with arguments (refreshes first, stops Play Mode).
unity_eval	code (string)	Evaluates C# expression or script dynamically in-memory against active Editor/Play Mode.
unity_stop	none	Safely terminates the background Unity Editor instance.

Auto-Start: If Unity is not running when an operation is requested, UnityCliRunner automatically starts a headless background instance in batchmode first.

---

Installation & Setup

1. Requirements

• .NET 10.0 Runtime or SDK (dotnet).
• Unity: Version 2021.3 or higher.

2. Install the Package

Install from OpenUPM:

openupm add com.pereviader.unityclirunner

Or add via git URL in Unity's Package Manager:

https://github.com/PereViader/UnityCliRunner.git?path=src/UnityCliRunner.Unity3d/Packages/com.pereviader.unityclirunner

3. Install MCP Configurations

In the Unity Editor menu, select: Tools > UnityCliRunner > Install MCP Configurations

This installs the repository launcher (.unity-cli/Launcher.cs) and configures your AI development tools:

• Repository-Portable Configurations (safe to commit to git):
  • VS Code: .vscode/mcp.json (uses servers schema and ${workspaceFolder})
  • Cursor: .cursor/mcp.json (uses mcpServers schema and ${workspaceFolder})
  • Claude Code: .mcp.json (uses mcpServers schema and ${CLAUDE_PROJECT_DIR:-.})
• Machine-Specific Configurations (gitignored):
  • Antigravity: .agents/plugins/unity-cli/mcp_config.json (uses absolute paths to .unity-cli/Launcher.cs and Unity project)
  • Codex: .codex/config.toml (uses absolute paths to .unity-cli/Launcher.cs and Unity project)

Client Limitations

• Codex & Antigravity: Because these clients do not support environment/workspace variable substitution in their local MCP configs, the installer writes absolute paths to .unity-cli/Launcher.cs and the Unity project directory. Through Launcher.cs, they still automatically resolve and track any future updates to com.pereviader.unityclirunner across Library/PackageCache.
• Claude Desktop: Claude Desktop only supports global user configurations (claude_desktop_config.json) rather than repository-level configurations. For Claude Desktop, configure the server in your global configuration using the launcher or absolute package path.

Manual MCP Server Configuration

For repository-portable configurations (e.g. VS Code, Cursor, Claude Code), invoke .unity-cli/Launcher.cs:

{
  "servers": {
    "unity-cli": {
      "command": "dotnet",
      "args": [
        "run",
        "--file",
        "${workspaceFolder}/.unity-cli/Launcher.cs",
        "--",
        "--project",
        "${workspaceFolder}/<relative-path-to-unity-project>"
      ]
    }
  }
}

---

CLI & Direct Invocation

The MCP binary can also be called directly from the command line for testing or scripting:

# Check status
dotnet Packages/com.pereviader.unityclirunner/MCP~/UnityCliRunner.Mcp.dll call unity_status

# Evaluate C#
dotnet Packages/com.pereviader.unityclirunner/MCP~/UnityCliRunner.Mcp.dll call unity_eval '{"code":"1 + 1"}'

# Refresh AssetDatabase
dotnet Packages/com.pereviader.unityclirunner/MCP~/UnityCliRunner.Mcp.dll call unity_refresh

# Run tests
dotnet Packages/com.pereviader.unityclirunner/MCP~/UnityCliRunner.Mcp.dll call unity_run_tests '{"mode":"editmode"}'

# Execute static method
dotnet Packages/com.pereviader.unityclirunner/MCP~/UnityCliRunner.Mcp.dll call unity_execute_method '{"methodName":"Tests.DummyExecuteClass.SuccessMethod"}'

---

License

MIT License. See LICENSE.md for details.