IsuzuUnityCli 4.3.3

Unity MCP Integration Framework

日本語版 | Tiếng Việt

This framework opens the Unity Editor to AI agents. Running a command by hand and calling it from a script go through the same path.

• MCP clients connect directly to the Streamable HTTP endpoint that the Editor itself publishes at http://127.0.0.1:<port>/mcp. There is no separate MCP server process. Checked with Claude Code, Cursor, Codex, the Gemini CLI, VS Code and Claude Desktop.
• The command line isuzu-unity-cli calls the same tools. The published binaries are native, so they need no Node and no .NET runtime.
• A tool is a static C# method with [McpTool] on it.

If this is your first time, start with Getting started with Unity MCP, an illustrated guide that walks through the installation.

Requirements

• Unity Editor 2022.3 or newer. The EditMode test suite is run on Unity 6000.0.35f1
• A Git client, 2.14.0 or newer, on PATH. Unity's Package Manager runs it to fetch a package from a git URL (Unity manual). The VPM repository below needs none
• com.unity.nuget.newtonsoft-json 3.2.1. It is resolved automatically as a dependency

Installation

In Unity's Package Manager choose Add package from git URL and enter:

https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp

With the VRChat Creator Companion (VCC) or ALCOM, add the VPM repository https://unity-mcp.shiranui-isuzu.dev/vpm.json instead. Both download a package as a zip, so that route needs no Git. The one-click add link, and where to find the button in each app, are on the getting started guide under If you use VCC or ALCOM.

Install the CLI:

# Windows
irm https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.sh | sh

You can also download a binary from GitHub Releases and verify it against SHA256SUMS. With the .NET 10 SDK installed, dotnet tool install -g IsuzuUnityCli works too.

Then install the agent skill and register an MCP client:

isuzu-unity-cli setup                              # the skill for Claude Code and Codex
isuzu-unity-cli setup --mcp --agent claude-code    # register an MCP client

--agent accepts claude-code, claude-desktop, codex, cursor, gemini or vscode. Claude Code files the server under the Unity project's path, so start Claude Code in the Unity project folder. Preferences > Unity MCP in the Editor can register a client as well.

Per-client configuration, the Claude Desktop extension bundle and the stdio bridge are in Connecting MCP clients.

First commands

The server starts when the Editor opens a project, and it publishes a descriptor file. The CLI reads that file, so you never type a port or a token.

isuzu-unity-cli projects                  # Editors currently running
isuzu-unity-cli tools                     # what this Editor publishes
isuzu-unity-cli call play_mode_status     # invoke a tool
isuzu-unity-cli verify                    # recompile, collect errors, read console errors

verify gathers the recompile and the error collection that follow a script edit into one call. Add --test and it runs the tests as well.

With several Editors open, choose one with --project <name>. Inside a project directory the choice is automatic. Every command is described in the CLI reference.

Tools

There are tools for diagnostics (console, Editor.log, compile status, tests, scene hierarchy, asset reads), authoring (create and change GameObjects, components, assets, scenes, prefabs and Animator Controllers), rendering, Timeline and Recorder, builds, running a C# snippet, and synthesizing Editor input. An authoring call collapses into a single undo step.

The Timeline tools appear only with com.unity.timeline, the Recorder tools only with both com.unity.recorder and com.unity.timeline, and test_run and test_results only with com.unity.test-framework.

The full list, with the things to know before editing, is in the tool reference. Append ?group=diagnostics,authoring to the MCP URL and tools/list returns only those groups.

Adding a tool

Write one method in the Editor.

using System.Linq;
using UnityMCP.Editor.Core;
using UnityMCP.Editor.Core.Attributes;

internal static class MyTools
{
    [McpTool(
        "asset_find_by_type",
        "Find project assets of a given type. Prefer a narrow type and a small limit.",
        Idempotency = McpIdempotency.Safe)]
    public static string[] FindByType(
        [McpArg("type", "Unity type name, e.g. Material.")] string type,
        [McpArg("limit", "Maximum paths to return.")] int limit = 50)
    {
        return UnityEditor.AssetDatabase.FindAssets($"t:{type}")
            .Take(limit)
            .Select(UnityEditor.AssetDatabase.GUIDToAssetPath)
            .ToArray();
    }
}

That is all it takes to call it from both MCP clients and the CLI. The JSON Schema comes from the signature. The properties [McpTool] accepts are listed in Architecture.

You can also add a tool from a JSON file without writing C#. See Defined tools.

Documentation

• Tool reference: every tool, with the things to know before editing
• Connecting MCP clients: per-client configuration, the Claude Desktop bridge, protocol facts
• CLI reference: every command, project selection, exit codes, what lands on your machine
• Defined tools: probe, script and sequence tools from a JSON file
• Synthesizing, recording and replaying Editor input: input_pointer, input_key, input_record, input_replay
• Architecture: the diagram, Editor-side classes, settings, tests
• Troubleshooting
• Security
• Updating: what to run for each version you might be on
• Migrating from v3
• CHANGELOG

Security

The server binds to 127.0.0.1 only, and every request except OPTIONS needs a bearer token. Treat the descriptor file and the token file as credentials: anything that can read them can run code in the Editor. Nothing ships in a player build, Development Build included. Details are in Security.

License

MIT