OTTLabs MCP Server

Gives any MCP-compatible AI assistant (Claude Code, Cursor, etc.) direct access to the Unity Editor. The assistant can inspect the scene hierarchy, move objects, create materials, bake lighting, manage VRCFury components, and much more -- all without leaving the chat.

How it works

AI assistant  <--- MCP (stdio) ---->  Python bridge  <--- HTTP/JSON ---->  Unity Editor
(Claude Code)                        bridge/unity_bridge.py              this package

1. Unity Editor runs an HTTP server on localhost:8765-8774.
2. Python bridge (bridge/unity_bridge.py) is a tiny MCP server that reads the port file and forwards tool calls.
3. AI assistant talks to the bridge over stdio using the standard MCP protocol.

---

Installation

Step 1 -- Install the Unity package

Add the package to your Unity project via the Package Manager Add package from git URL:

https://git.ott-labs.de/OTT-Labs/OTTLabsMCP.git

Or add it manually to Packages/manifest.json:

{
  "dependencies": {
    "de.ott-labs.ottlabs-mcp": "https://git.ott-labs.de/OTT-Labs/OTTLabsMCP.git"
  }
}

Open or restart the Unity Editor. The server starts automatically and logs:

[OTTLabsMCP] Listening on http://localhost:8765/

Use OTT Labs -> OTTLabs MCP -> Server Status to confirm it is running.

Step 2 -- Install the Python bridge

Requires Python 3.11+.

# with pip
pip install mcp httpx

# or with uv (recommended)
uv pip install mcp httpx

Step 3 -- Configure your MCP client

Claude Code

Add to ~/.claude/claude_code_config.json (create it if it does not exist):

{
  "mcpServers": {
    "unity": {
      "command": "python",
      "args": ["/absolute/path/to/OTTLabsMCP/bridge/unity_bridge.py"],
      "env": {
        "UNITY_PROJECT_PATH": "/absolute/path/to/your/unity/project"
      }
    }
  }
}

Replace both paths with the real absolute paths on your machine.

Other MCP clients

Configure a stdio MCP server with:

• Command: python /path/to/bridge/unity_bridge.py
• Environment: UNITY_PROJECT_PATH=/path/to/your/unity/project

---

Verification

With Unity running and the bridge configured, ask Claude Code:

"Show me the scene hierarchy."

Claude will call the scene_hierarchy tool and return the full tree.

---

Environment variables

Variable	Required	Description
UNITY_PROJECT_PATH	Yes	Absolute path to the Unity project root. The bridge reads Temp/OTTLabsMCPPort.txt from here.

---

Security

Each time Unity starts, a fresh random auth token is generated and written alongside the port to Temp/OTTLabsMCPPort.txt as {port}:{token}. The bridge reads this token and sends it as an Authorization: Bearer <token> header. Requests without a valid token receive a 401 response.

The server only binds to localhost and never accepts remote connections.

---

Troubleshooting

Bridge says "OTTLabs MCP server not found"

• Make sure the Unity Editor is open.
• Check that the OTTLabs MCP package is installed (Package Manager -> In Project).
• Confirm UNITY_PROJECT_PATH points to the correct project folder.
• Look in Temp/OTTLabsMCPPort.txt -- it should contain a port:token pair.

"Unauthorized" errors

• The token rotates on every Unity restart. Restart the bridge (restart Claude Code / your MCP client) so it re-reads the port file.

Port binding failed in Unity

• Check the Unity Console for [OTTLabsMCP] log lines.
• Use OTT Labs -> OTTLabs MCP -> Restart Server to retry.

Long operations time out (lighting bake, VRC build)

• The default HTTP timeout in the bridge is 90 seconds. These operations can take longer. Use the cancel endpoint (lighting_bake_cancel) to abort, or increase timeout in _post() inside unity_bridge.py.

---

Available tools (94 total)

Tools are discovered dynamically from Unity via tools/list -- no hard-coding in the bridge. The full list is always up-to-date with the installed package version.

Category	Tools
Scene query	scene_hierarchy, scene_object, scene_find, scene_info
Scene modify	scene_create, scene_delete, scene_set_transform, scene_set_field, scene_add_component, scene_instantiate, scene_reparent, scene_rename
Assets	assets_list, assets_find, assets_create_material
Editor	editor_save, editor_refresh, editor_select, editor_ping
Windows	editor_window_open, editor_window_close, editor_window_list, editor_execute_menu
Lighting	lighting_get, lighting_set, lighting_bake, lighting_bake_cancel, lighting_clear
VRChat SDK	vrchat_info, vrchat_validate, vrchat_build_test, vrchat_build_upload, vrchat_descriptor_get, vrchat_descriptor_set
Build	build_settings, build_switch_platform
Avatar	avatar_strip_unused_bones
Texture	texture_create (6 generation modes)
Mesh	mesh_create (5 modes), mesh_get, mesh_modify
Terrain	terrain_create, terrain_get, terrain_resize, terrain_set_heights, terrain_apply_craters, terrain_add_layer, terrain_to_mesh, terrain_bake_height_texture
VRCFury	vrcfury_list, vrcfury_get, vrcfury_list_feature_types, vrcfury_add_toggle, vrcfury_add_feature, vrcfury_remove, vrcfury_set_field, vrcfury_add_object_action, vrcfury_add_blendshape_action
OT&T MQTT	ott_mqtt_manager_status/inject/refresh, ott_mqtt_driver_status/connect/disconnect/publish/fault
OT&T VR Phone	ott_vrphone_* (17 tools for layout editing, atlas baking, canvas build)
OT&T ScribanGen	ott_scriban_generate_all, ott_scriban_generate_asset, ott_scriban_list_bindings

---

License

MIT -- see package.json.