@euqns/unity-behavior-tree-mcp

An MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, etc.) author and edit Unity Behavior Graph assets (com.unity.behavior 1.0+) directly in the Unity Editor.

The agent gets typed tools for creating graphs, adding/connecting nodes, configuring node fields, and managing blackboard variables. Unity stays the source of truth — every change goes through BehaviorAuthoringGraph and the runtime graph is rebuilt automatically.

How it works

┌─────────────────────────┐    stdio (MCP)    ┌────────────────────────────┐    HTTP    ┌──────────────────┐
│ Claude Code / Desktop / │ ────────────────► │ @euqns/unity-behavior-tree │ ─────────► │ Unity Editor     │
│ Cursor / any MCP client │                   │     -mcp (Node server)     │            │ Bridge (UPM pkg) │
└─────────────────────────┘                   └────────────────────────────┘            └──────────────────┘
                                                                                         BehaviorAuthoringGraph
                                                                                         + Blackboard

Two pieces ship together:

• Node MCP server (this npm package) — talks to your MCP client over stdio, exposes a typed tool surface.
• Unity Editor bridge (UPM package under unity-bridge/) — runs an HTTP listener inside the Unity Editor (127.0.0.1:17777 by default) and uses Unity Behavior's authoring API to make the changes.

Install

1. Install the Unity Editor bridge

Open Packages/manifest.json in your Unity project and add:

{
  "dependencies": {
    "com.euqns.unity-behavior-tree-mcp": "https://github.com/kubilayege/unity-behavior-tree-mcp.git?path=/unity-bridge",
    "com.unity.behavior": "1.0.15",
    "com.unity.nuget.newtonsoft-json": "3.2.1"
  }
}

Or use Package Manager → Add package from git URL with: https://github.com/kubilayege/unity-behavior-tree-mcp.git?path=/unity-bridge

For local development you can also point at a local checkout:

"com.euqns.unity-behavior-tree-mcp": "file:../path/to/unity-bridge"

The bridge auto-starts when the Editor opens. Use Tools → Behavior Tree MCP to start/stop/restart or change the port (Preferences → Behavior Tree MCP).

2. Configure your MCP client to launch the server

Claude Code

claude mcp add unity-behavior-tree -- npx -y @euqns/unity-behavior-tree-mcp

Claude Desktop / Cursor (manual JSON)

{
  "mcpServers": {
    "unity-behavior-tree": {
      "command": "npx",
      "args": ["-y", "@euqns/unity-behavior-tree-mcp"],
      "env": {
        "UNITY_BRIDGE_URL": "http://127.0.0.1:17777"
      }
    }
  }
}

Environment variables

| Var | Default | Purpose | |---|---|---| | UNITY_BRIDGE_URL | http://127.0.0.1:17777 | Bridge endpoint. Change if you set a different port in Editor preferences. | | UNITY_BRIDGE_TIMEOUT_MS | 30000 | Per-request timeout. |

Tool surface

The server exposes 16 tools, grouped by domain.

Discovery

• unity_ping — sanity-check the bridge is up; returns Unity + package versions.
• list_node_types — every node type registered in the project (built-ins and your custom [NodeDescription] actions), with their categories, kinds, named child ports, and field schemas.

Graph CRUD

• list_graphs — every BehaviorAuthoringGraph asset.
• create_graph — new graph at an Assets/.../*.asset path. Seeds a Start node by default.
• get_graph — full snapshot: nodes (id, type, position, field values), edges, blackboard.
• save_graph — explicit save + runtime rebuild (most edits auto-save).
• delete_graph — destructive, will prompt.

Nodes

• add_node — create a node by typeId; can connect to a parent in the same call.
• connect_nodes / disconnect_nodes — wire parent → child (named ports supported for composites).
• set_node_field — set a literal value or link the field to a blackboard variable.
• move_node — change canvas position.
• remove_node — delete by id (cleans up edges).

Blackboard

• list_blackboard_variables
• add_blackboard_variable — typed (int/float/bool/string/Vector3/GameObject/your enums/etc.).
• set_blackboard_variable — change value, rename, toggle shared/exposed.
• remove_blackboard_variable

A typical AI workflow

1. unity_ping → confirm the Editor is open and the bridge is running.
2. list_node_types → know what actions / composites / your custom nodes exist.
3. create_graph → spawn Assets/AI/Enemy.asset.
4. add_blackboard_variable → declare target: GameObject, attackRange: float.
5. add_node Sequence/Selector/etc., chained with parentNodeId to wire as you go.
6. set_node_field → either literal values ({value: 5.0}) or {blackboardVariableName: "attackRange"} to link.
7. get_graph → verify structure before handing the asset off.

Custom node types

Any class you author with [NodeDescription] (action, composite, modifier, conditional, event action) automatically appears in list_node_types after Unity recompiles — no extra configuration needed. The MCP server pulls live data from Unity's NodeRegistry, so AI agents always see the same node palette you do.

Notes & limitations

• Editor only. The bridge runs inside the Unity Editor — it doesn't operate on closed projects or runtime builds.
• Localhost only. The HTTP listener binds to 127.0.0.1 and accepts no remote connections.
• Internal API use. com.unity.behavior 1.0 keeps most authoring types internal; the bridge uses reflection. If a future Unity Behavior release rearranges class names, the bridge needs an update — pin the package version you tested against.
• No subgraph creation yet. You can author a graph that references an existing subgraph via add_node (using SubgraphNodeModel's typeId), but tooling for creating subgraphs is on the roadmap.

Develop locally

git clone https://github.com/kubilayege/unity-behavior-tree-mcp.git
cd unity-behavior-tree-mcp
npm install
npm run build         # one-shot build
npm run dev           # tsc --watch

# In Unity, add the unity-bridge as a local file dependency:
#   "com.euqns.unity-behavior-tree-mcp": "file:../path/to/this/repo/unity-bridge"

Point your MCP client at the local dist:

{
  "command": "node",
  "args": ["/abs/path/to/unity-behavior-tree-mcp/dist/index.js"]
}

License

MIT