unityctl-mcp 0.6.5

unityctl

English | 한국어

The execution layer for AI-driven game development.

Give your AI agent 179 commands to build Unity scenes, write C# scripts, validate builds, and ship games — with automatic rollback when things go wrong.

179 CLI commands · 12 MCP tools · 966 PR .NET tests · Windows / macOS / Linux

<p align="center"> <img src="docs/assets/unityctl-demo.gif" alt="Live unityctl session: status, scene hierarchy, mesh create-primitive, gameobject find, screenshot capture — every response written to out/ as an artifact" width="820"> </p>

<p align="center"><em>Unrehearsed session against a live Unity 6000.3.16f1 Editor — every command answers in structured JSON and drops an artifact in <code>out/</code>.</em></p>

Benchmarked head-to-head against the official Unity CLI (1.0.0-beta.2 + com.unity.pipeline) on the same editor session — faster round-trips, smaller responses, and every measured gap absorbed the same day. See the benchmark.

Quality gates: every PR runs the .NET Shared/Core/Cli/Mcp test suites on Windows, macOS, and Linux. Unity Editor-dependent validation is separated into the Unity Integration workflow, with init, sample-project doctor, check, scene hierarchy, player-settings set/get, and workflow verify evidence uploaded from nightly/manual runs. Unity Integration requires either a UNITY_LICENSE or UNITY_SERIAL GitHub secret.

Contributors: see CONTRIBUTING.md for the test trust checklist, flaky-test policy, command sync checklist, and Unity live-validation split.

The Problem

AI agents can write code, but they can't build games — because Unity has no programmatic interface for scene editing, asset management, or project validation.

Existing Unity MCP servers try to fix this, but they create new problems for AI agents:

The Solution

unityctl is a .NET CLI + MCP server that turns Unity Editor into a programmable API.

For AI agents, this means a closed-loop automation cycle — the agent doesn't just execute commands, it can verify results, diagnose failures, and recover from mistakes:

<p align="center"> <img src="docs/assets/agent-loop.svg" alt="Plan - Execute - Verify - Diagnose Loop" width="680"> </p>

Other tools give agents hands. unityctl gives agents hands, eyes, and a safety net.

Why unityctl for AI Agents?

Token Efficiency

AI agent costs are dominated by tool schemas sent every turn. unityctl uses on-demand schema loading:

<p align="center"> <img src="docs/assets/token-efficiency.svg" alt="Measured token cost: unityctl via Bash = 0 overhead, 6.8x cheaper than CoplayDev MCP" width="620"> </p>

The CLI exposes 179 entry points, including convenience wrappers. The 12 MCP tools keep prompts small by loading 171 canonical command schemas on demand through unityctl_query, unityctl_run, and unityctl_schema.

Install

Standalone binary — no .NET SDK required (recommended):

# macOS (Apple Silicon) — swap in unityctl-osx-x64 / unityctl-linux-x64 as needed
curl -L https://github.com/Jason-hub-star/unityctl/releases/latest/download/unityctl-osx-arm64.tar.gz | tar xz
./unityctl --version

Windows: download unityctl-win-x64.zip from Releases and unzip. Each archive contains a self-contained unityctl + unityctl-mcp executable and the embedded Unity plugin template.

Or via .NET tool (requires .NET 10 SDK):

dotnet tool install -g unityctl
dotnet tool install -g unityctl-mcp

Optional agent workflow skill for Claude Code and Codex:

npx skills add Jason-hub-star/unityctl \
  --skill unityctl-workflows \
  -a claude-code -a codex

The skill teaches agents to discover the live command surface, target the right Unity project, and close every edit with structured readback and verification.

Bootstrap notes:

• --source accepts a local Unityctl.Plugin folder or a Git URL: https://github.com/Jason-hub-star/unityctl.git?path=/src/Unityctl.Plugin#v0.6.5

Quick Start

# 1. Install the Editor plugin
unityctl init --project /path/to/project \
  --source "https://github.com/Jason-hub-star/unityctl.git?path=/src/Unityctl.Plugin#v0.6.5"

# 2. Open the project in Unity Editor, then verify connectivity
unityctl ping --project /path/to/project --json
unityctl status --project /path/to/project --json

# 3. Start building
unityctl gameobject create --name "Player" --project /path/to/project
unityctl component add --id "<PlayerId>" --type "Rigidbody" --project /path/to/project
unityctl scene save --project /path/to/project

# 4. Validate
unityctl project validate --project /path/to/project --json

# 5. Build
unityctl build --project /path/to/project --dry-run    # 13 preflight checks

MCP Setup (AI Agents)

One command per client — it merges into the existing config instead of replacing it:

unityctl mcp install --client claude-code            # or cursor / codex
unityctl mcp install --client vscode --project .     # VS Code is workspace-scoped
unityctl mcp install --client cursor --dry-run       # preview, writes nothing

Or add it by hand:

{
  "mcpServers": {
    "unityctl": {
      "command": "unityctl-mcp"
    }
  }
}

Documentation

• Command Reference — all 179 CLI commands and the 12 MCP tools
• README Appendix — worked examples, architecture, platform support
• Getting Started — installation, setup, and common workflows
• AI Agent Quickstart — MCP setup and agent integration guide
• Showcase Roadmap — recommended demo game ladder, asset checklist, and pre-production plan
• Architecture — system design and transport diagrams
• Glossary — key terms and concepts

Changelog

See GitHub Releases for version history.

License

MIT — see LICENSE