UnityMCP

UnityMCP is a local Streamable HTTP MCP server that exposes Unity Editor inspection, authoring, testing, profiling, play-mode, and build tools. Its core has no compile-time dependency on a game's scripts or on Netcode for GameObjects.

Requirements

• Unity 6 (6000.0 or newer)

• A local MCP client such as Codex

• The package dependencies declared in package.json (Unity installs these through UPM)

Install

Use one of these approaches:

1. In Unity Package Manager, choose Add package from git URL and enter:

   https://github.com/zloybest/UnityMCP.git#v0.23.0

   The repository must be accessible to Git on that computer.

2. For local development, copy this entire directory into the other project's Packages/com.zloybest.unitymcp directory. Keep package.json, the assembly definition, source files, and .meta files together.

Do not copy only the .cs files: the package manifest supplies required Unity packages, and the assembly definition prevents accidental references to the host game's assemblies.

The complete command and protocol reference is in Documentation~/UnityMCP.md.

Configure Unity

1. Wait for Unity to finish importing and compiling.

2. Open Tools > Unity MCP > Control Window.

3. Leave Auto Start enabled or start the server manually.

4. Choose a free port. The default is 8090; use a different port for each concurrently open Unity project.

5. Click Restart after changing the port.

6. Confirm the endpoint shows http://127.0.0.1:<port>/.

Settings are stored per Unity project in ProjectSettings/UnityMCPSettings.asset.

When Unity Multiplayer Play Mode launches additional Editor instances, UnityMCP keeps the endpoint exclusively in the main Editor. Additional Editors detect Unity's virtual project launch marker (and CurrentPlayer.IsMainEditor when available) and suppress server startup, preventing a clone from capturing the configured port during domain reload. Requests from non-loopback addresses are rejected.

Connect an MCP client

UnityMCP supports two client connection approaches:

On Windows, UnityMCP already uses its own reload-safe endpoint broker, so direct mode is usually sufficient. The optional proxy adds client-side retries and keeps the MCP stdio process stable. On other platforms, it is also useful while Unity's HTTP listener restarts.

Option A: direct HTTP

Run this once, replacing the name/port if necessary:

codex mcp add UnityMCP --url http://127.0.0.1:8090/

Equivalent config.toml configuration:

[mcp_servers.UnityMCP]
url = "http://127.0.0.1:8090/"
startup_timeout_sec = 10.0
tool_timeout_sec = 180.0

Use a distinct server name (for example UnityMCP_OtherGame) when registering more than one Unity project. Restart Codex or begin a new session after changing MCP config, then call the ping tool to verify the connection.

Option B: reload-tolerant stdio proxy

Clone this repository to a stable path and point Codex at the included zero-dependency proxy. Do not use a path inside Unity's Library/PackageCache: package cache paths can change after an update.

codex mcp add UnityMCP -- node "C:\path\to\UnityMCP\Proxy~\index.js" --stdio

Equivalent config.toml configuration on Windows:

[mcp_servers.UnityMCP]
command = "node"
args = ['C:\path\to\UnityMCP\Proxy~\index.js', "--stdio"]
startup_timeout_sec = 10.0
tool_timeout_sec = 180.0

The proxy targets http://127.0.0.1:8090/ by default. For another UnityMCP port, add:

[mcp_servers.UnityMCP.env]
TARGET_URL = "http://127.0.0.1:8092/"

It retries transient connection failures, HTTP 502/503/504, and Unity's empty domain-reload response, then returns a retryable JSON-RPC error if Unity remains unavailable. No npm install is needed. See Proxy~/README.md for retry, logging, HTTP-proxy, and authentication options.

The old names KebabMCP and KebabProxy are obsolete. Existing configurations should rename the server table to mcp_servers.UnityMCP and update the script path to this repository's Proxy~\index.js.

Optional integrations

• Netcode tools discover Netcode for GameObjects at runtime. Without NGO, status/list commands return empty state and start commands report that the integration is absent.

• Projects with a compatible GameManager session API automatically keep the relay/session-code flow; otherwise host/client start falls back to NGO NetworkManager.

• devtools_toggle_f3 and devtools_toggle_f4 are compatibility tools. They discover supported DevTools types at runtime and return not_found in projects without them.

• Scripted input tools use Unity Input System, installed as a package dependency.

• play_start keeps its no-argument default solo behavior. On Unity versions that provide the Play Mode Framework, pass playModeConfig as a configuration asset path or exact asset name to start that configuration. Multiplayer Play Mode scenario assets are supported without a compile-time dependency on the MPM package.

Updating

Update the Git package through Package Manager, or replace the copied package directory with a newer complete version. Reopen Unity and verify ping reports the expected version.

Development and tests

To work on the package locally, use Package Manager's Add package from disk command and select this repository's package.json. Add com.zloybest.unitymcp to the host project's testables array to expose the package's Edit Mode tests in Unity Test Runner.