# 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`](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:

| Approach | Best fit | Tradeoff |
| --- | --- | --- |
| Direct Streamable HTTP | Simplest setup and lowest overhead. Recommended when the client tolerates a brief Unity reload. | A request can fail if it lands during compilation or a domain reload. |
| Stdio proxy | Long-running sessions where reload resilience matters most. | Requires Node.js 18+ and a stable checkout of this repository. |

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:

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

Equivalent `config.toml` configuration:

```toml
[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.

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

Equivalent `config.toml` configuration on Windows:

```toml
[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:

```toml
[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`](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.