convez.ai
MCP ServerAutomaçãoAvançado
german-krasnikov

Unity MCP — Controle do Editor Unity via Claude

german-krasnikov/unity-kiss-mcp

Controle Unity Editor do Claude sem sair do chat — 80-95% economia de tokens

Ver no GitHub
InicialPluginScore · de 0 a 100

Server MCP que permite controlar o Unity Editor diretamente do Claude ou qualquer assistente IA compatível com MCP. Oferece 91 ferramentas para inspeção de cenas, edição de GameObjects, execução de playtests e captura de screenshots, com protocolo TCP binário que economiza 80-95% de tokens em operações em lote.

Instalação

$npx convez-ai german-krasnikov/unity-kiss-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
32
Forks
4
Acompanhando
0
Saúde
42%
Último commit
há 2 dias
Versão
v3.0.3
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de tarefas de edição no Unity via assistente IA
  • Inspeção e modificação de cenas durante desenvolvimento
  • Execução de playtests e captura de screenshots automatizados
  • Prototipagem rápida com assistência de IA sem alt-tab

Veredito

Solução técnica robusta e bem arquitetada para integração profunda entre Claude e Unity. Destaca-se pela otimização agressiva de tokens (80-95% em lotes) e sistema de plugins extensível, ideal para times que querem automação séria no workflow de desenvolvimento de games.

README

A tradução para o português deste README ainda está na fila.

Unity MCP — Control Unity Editor from Any AI Assistant

STATUS

SPEC

STACK

Let any MCP-compatible AI assistant control your Unity Editor — inspect scenes, edit GameObjects, run playtests, and capture screenshots without leaving the chat. Binary TCP protocol with 10–15× token compression and 80–95% batch savings.

MCP (Model Context Protocol) is Anthropic's open standard for giving AI assistants structured tool access.

Why Unity MCP?

  • Stop alt-tabbing. Your AI assistant inspects your scene, edits components, runs playtests, and captures screenshots without you leaving the chat.
  • Stop burning tokens on boilerplate. Each batch call replaces 5–20 individual round-trips — 80–95% fewer tokens on the same work.
  • Stop writing glue code. Registered tools cover scene CRUD, animation, VFX, UI, shaders, runtime control, and code intelligence — with a plugin seam for your own.

Two ways to work

🖥️ CLI Mode — run from terminal via Claude Code, Codex CLI, or any MCP client. The Python server connects to Unity over TCP :9500. Best for automation, batch operations, and scripting. Full access to 94 MCP tools with 80–95% token compression.

💬 In-Unity Chat — open Window → MCP Chat inside the editor. No API key needed — spawns the Claude or Codex CLI directly. Drag GameObjects, scripts, and materials into chat as typed context chips. Each AI turn gets its own undo group — one Ctrl+Z rolls back everything the AI changed. Domain-reload safe. Extensible chip-kind registry lets third-party plugins add new chip types with zero core edits.

Before / after — creating and configuring 3 objects:

# Before: 9 separate MCP calls (~1800 tokens)
create_object("Enemy")
set_property("Enemy", "Transform", "position", "0,1,0")
manage_component("Enemy", "add", "Health")
set_property("Enemy", "Health", "maxHp", "100")
# ... 5 more calls
# After: 1 batch call (~120 tokens, 93% savings)
batch([
  {"cmd": "create_object",    "path": "Enemy", "type": "Empty"},
  {"cmd": "set_property",     "path": "Enemy", "component": "Transform", "property": "position", "value": "0,1,0"},
  {"cmd": "manage_component", "path": "Enemy", "action": "add", "component": "Health"},
  {"cmd": "set_property",     "path": "Enemy", "component": "Health", "property": "maxHp", "value": "100"},
])

Architecture

Quick Start

Prerequisites: Python 3.10+ · Unity 6000.0+ · Claude Code or Codex CLI · TCP port 9500 free

1. Install the Python server

git clone https://github.com/german-krasnikov/unity-kiss-mcp.git
cd unity-kiss-mcp/server && pip install -e ".[dev]"

2. Install the Unity plugin

Add to your project's Packages/manifest.json:

{
  "dependencies": {
    "com.unity-mcp.editor": "file:/absolute/path/to/unity-kiss-mcp/unity-plugin"
  }
}

Open Unity — wait for [MCP] Server started on port 9500 in the Console.

3. Configure your MCP client

Add to ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "python",
      "args": ["-m", "unity_mcp.server"],
      "cwd": "/absolute/path/to/unity-kiss-mcp/server"
    }
  }
}

Restart Claude Code. Call get_hierarchy() to verify.

Add to .codex/config.toml in your project root:

[mcp_servers.unity-mcp]
command = "python"
args = ["-m", "unity_mcp.server"]
cwd = "/absolute/path/to/unity-kiss-mcp/server"

Use the standard mcpServers JSON block — same structure as Claude Code but in your client's config file. The server uses stdio transport.

  • Port 9500 not listening — Ensure plugin is in manifest.json. Click Unity window to recompile. Check Console.
  • "Connection refused" — Unity must be open with the plugin. Server auto-retries on reconnect.
  • Tools don't appear — Verify path in mcp_settings.json. Restart Claude Code. pip show unity-mcp.
  • C# changes not reflected — Click Unity window or open -a Unity (macOS) to trigger recompile.
  • Security — TCP server binds to localhost only. Do not expose port 9500 to the network.
ComponentTestedMinimum
Unity6000.36000.0 (Unity 6)
Python3.123.10
OSmacOSmacOS, Windows, Linux
Claude Codelatestany with MCP support
Codex CLIlatestany with MCP support
Claude Desktoplatestany with MCP support

Features

  • Token Optimization — batch compresses 5–20 calls into one (80–95% savings), deferred tool schemas, per-session cost analytics
  • In-Unity Chat — Claude/Codex backends, no API key needed, typed context chips ([hierarchy:/Player], [script:Health.cs]), per-turn undo, domain-reload safe
  • Code Intelligence — Roslyn-powered find_references, compile_preflight, semantic_at
  • PlayTest DSL — 21 commands: MOVE, ASSERT, WAIT_UNTIL, INVOKE, SNAPSHOT, SIMULATE
  • Multi-Scene Management — Load multiple scenes, inspect/edit across scenes, move/copy objects between loaded scenes, unified object_diff for cross-scene comparison
  • Scene CRUD & Tools — scene actions (open_additive, close, set_active, list), hierarchy inspection, query syntax, diff tracking, checkpoint/restore
  • Animation & Timeline — clips, key management, Timeline assets, Animator states/transitions
  • VFX & Particles — particle system CRUD, 11 module presets, shader graph integration
  • Multi-View Screenshots — 4-panel grid (Front/Left/Top/Iso), bounding-box overlay, visual regression
  • Multi-Project Ports — each Unity project auto-assigns a unique TCP port (9500–9599), CLI and Chat get isolated slots
  • Capability Gating — TIER1 core always on; 8 category toggles per-session
  • Cross-Platform — Windows, macOS, Linux — binary resolution, lockfile, and venv per platform
  • Plugin Extensibility — register your own tools in one file, no cross-imports
run_playtest(script="""
MOVE /Player TO 5,0,3
WAIT_UNTIL /Enemy|Health|hp <= 0 timeout=5
ASSERT /Player|Health|hp > 0
ASSERT_CONSOLE_CLEAN
SNAPSHOT /Player /Enemy
""")
# server/src/unity_mcp/tools/my_tool.py
def register(mcp, send, args):
    @mcp.tool()
    async def find_inactive(path: str = "/") -> str:
        """Find all inactive GameObjects under path."""
        return await send("find_objects", args(path=path, active="false"))

Drop the file in tools/ — it's auto-discovered on next server start.

Recent Changes

UTF-8 Encoding Round-3 (Server + Plugin v0.25.13) — (C1: Python test I/O gates) All bare open(..., "r") in test suite now explicit `encoding …

UTF-8 Everywhere (Server + Plugin v0.25.12) — (Round 1) Python file I/O and C# Windows codepage safety hardening.

Multi-Scene CRUD + Diff (Plugin v0.25.0) — Cross-scene transfer_object (move/copy between scenes), object_diff (unified diff of two objects sh …

Port Re-Discovery on Reconnect (Server v0.24.1) — UnityBridge now auto-rediscovers Unity's port when reconnecting after a restart.

Multi-Scene Hierarchy Support (Plugin v0.24.0) — get_hierarchy now handles multiple loaded scenes with scene-aware context headers.

  • v0.23.13 — 2026-06-11 — Unified settings + media viewers + LLM config + review hardening
  • v0.23.0 — 2026-06-11 — Reconnect recovery + installer + unified settings + media viewers + DRY sampling
  • v0.22.1 — 2026-06-11 — Crash logging for unhandled MCP server exceptions
  • v0.22.0 — 2026-06-11 — Multi-project port auto-assignment + dual-port isolation + PortResolver extraction
  • v0.21.0 — 2026-06-11 — Cross-platform Windows/Linux support + zero manual patching
  • v0.20.7 — 2026-06-10 — Reload-resume re-sends the full-path chip payload, not short-name mentions (task#10)
  • v0.20.6 — 2026-06-10 — Full-path chip payload + always-raw "Show LLM payload" inspector for every turn type
  • v0.20.0 — 2026-06-10 — Chip-unification Phase 1 — delete SceneNameLinker path, unified @-mention rendering
  • v0.19.2 — 2026-06-10 — Chat reload double-bubble MAJOR + drag-drop crash guard + clean test console
  • v0.19.1 — 2026-06-10 — P0/P1 chat UX hardening — ResetTurnFlags DRY, bubble dedup, backend restore race
  • v0.19.0 — 2026-06-10 — Chat UX F27–F30 — Domain reload + external drag/drop + input height + backend cleanup
  • v0.18.0 — 2026-06-10 — Chat UX F20–F26 — Stop button, reload survival, AutoScroll, dropdown persist, @Object dedup, direct Clear, drag/drop MonoScript
  • v0.17.36 — 2026-06-06 — Settings Hub redesign — central hub UI + circuit-node header animation + Claude foldout grouping
  • v0.17.34 — 2026-06-06 — F25 Phase 2 settings hub — unique thematic header animations per sub-window
  • v0.17.28 — 2026-06-06 — F23 settings split — 3 focused EditorWindows + Chat event hook
  • v0.17.20 — 2026-06-06 — 40-architect test audit — 299 new tests total, 3 P0+P1 bug fixes
  • v0.17.18 — 2026-06-06 — F20–F22 bugfixes — select-all, @mention search, orphan bold
  • v0.17.17 — 2026-06-05 — F15a-F19 chip redesign — linker disable, leading-space guard, context menus
  • v0.17.14 — 2026-06-05 — F13–F14 inline-chip architecture + bare-name normalizer + review fixes
  • v0.17.2 — 2026-06-05 — inline context chips + review fixes (regex + staleness + test DRY)
  • v0.17.0 — 2026-06-05 — full-project code review sprint — 12 waves of fixes across Python + C#
  • v0.16.0 — 2026-06-05 — F12 chat UX overhaul — composed inline-chip field + response pills + session clear
  • v0.15.8 — 2026-06-05 — inline-chips + extensible chip-kind registry — F11
  • v0.15.0 — 2026-06-04 — chat UX polish sprint — F1–F10 + review-hardening
  • v0.14.0 — 2026-06-04 — multi-backend agent chat — Claude + Codex via DRY CliBackendBase
  • v0.7.1 — 2026-06-04 — tech-debt sprint wave 1–3 (Python/C#/Chat) — pure quality
  • v0.7.0 — 2026-06-04 — Editor.log out-of-band corroboration — P0 compile-tool blindness fix
  • v0.6.1 — 2026-06-04 — atomic batch rollback — transactional scene edits
  • v0.5.0 / 0.12.0 — 2026-06-04 — scoped scene queries — search_scene root+limit + spatial center
  • v0.11.0 — 2026-06-04 — per-turn undo rollback + Restore button
  • v0.10.0 — 2026-06-04 — chat plan/act approve & execute + slash templates
  • v0.9.0 — 2026-06-04 — chat context resolution + compile gating tool
  • v0.8.0 — 2026-06-04 — compile auto-fix + editor-state injection + tool ping
  • v0.7.0 — 2026-06-04 — F4 deferred schema + reload-survival + auto-selection
  • v0.6.0 — 2026-06-03 — Aura pill + native theme + perms gating
  • v0.5.0 — 2026-06-03 — chat UX polish — refs, grouping, scroll
  • v0.4.0 — 2026-06-03 — extensible render: md + mermaid + img
  • v0.3.0 — 2026-06-03 — in-Unity Agent Chat + UIToolkit status
  • v0.2.6 — 2026-06-02 — tool-gating fix + settings UI

Contributing

# Python tests (no Unity needed)
cd server && pytest -m "not live" -v

# With Unity running on :9500
pytest -m "live"

# C# tests — Unity Test Runner → EditMode

Architecture overview: AI/architecture.md · Full tool catalog: AI/mcp-server.md

Ver o original no GitHub

Bom para

Relacionados