Unity Code MCP Server

Unity Code MCP Server is a powerful tool for the Unity Editor that gives AI Agents ability to perform any action using Unity Editor API. This includes scripts, scenes, prefabs, assets, configuration changes, and more.

Real workflow example

<details> <summary><strong>User prompt</strong></summary>

Add following feature to Unity using execute script tool:

- Read cities list from csv file #file:cities.csv
- Create CitySO ScriptableObject class with properties based on csv columns, place it in Assets/Scripts/ScriptableObjects
- Create assets for each city in the csv file, populate properties with data from the file, place them in Assets/ScriptableObjects
- Create CityComponent MonoBehaviour class with a reference to CitySO ScriptableObject and place it in Assets/Scripts
- Create Map root gameobject in the current scene
- For each city asset, create a City gameobject as a child of Map, set its position based on the coordinates from the asset, add CityComponent and assign the corresponding CitySO asset
- To each City gameObject add SpriteRenderer component and assign a default sprite from Assets/Images/City.png

</details> <details> <summary><strong>AI Agent Result</strong></summary>

Implemented the full “cities from CSV → assets → scene” pipeline.

- Added `CitySO` ScriptableObject: CitySO.cs
- Added `CityComponent` MonoBehaviour: CityComponent.cs
- Added the CSV data file: cities.csv
- Ran an Editor execution script that:
  - Created 49 `CitySO` assets in ScriptableObjects
  - Created a `Map` root GameObject in the active scene with 49 `City` children
  - Set each city position from `Coordinates`, added `CityComponent` and assigned the matching `CitySO`
  - Added `SpriteRenderer` to each city and assigned the default sprite from City.png

</details>

Full chat transcript: ChatTranscript.md. Repository contains solution with result.

Table of contents

• Features
• Security considerations
• Architecture
• Quick start
• Built-in tools
• Agent skills
• Extending (adding tools)
• Script execution context
• STDIO bridge
• Testing
• Known Issues
• License

Features

• Unity Editor / Unity Engine API access: Perform any tasks available through public APIs or reflection
• STDIO transport (via bridge): No separate server process required for MCP clients. Domain-reload safe, retries if domain reload is in progress. uv (Python package manager) is required.
• Streamable HTTP transport: Alternative to STDIO bridge for MCP clients that support HTTP. No separate server process required. No uv required. Responds with error if domain reload is in progress.
• Extensible: Add new tools, async tools, resources, or prompts by implementing interfaces anywhere in the codebase

Tools

execute_csharp_script_in_unity_editor

Perform any task by executing generated C# scripts in Unity Editor context. Full access to UnityEngine, UnityEditor APIs, and reflection. Automatically captures logs, errors, and return values.

read_unity_console_logs

Read Unity Editor Console logs with configurable entry limits (1-1000, default 200)

run_unity_tests

Run Unity tests via TestRunnerApi. Supports EditMode, PlayMode, or both. Can run all tests or filter by fully qualified test names.

Security considerations

This package executes LLM-generated C# code (including reflection code) with the same privileges as the Unity Editor process.

Recommendations:

• Review scripts before executing them.
• Use a separate Unity project and/or run Unity in an isolated environment (VM/container).

You are responsible for securing your environment and for any changes or data loss caused by executed scripts.

Architecture

STDIO Transport

┌─────────────┐     STDIO      ┌─────────────────┐      TCP      ┌────────────────────────────┐
│  MCP Client │ ◄────────────► │  STDIO Bridge   │ ◄───────────► │   Unity Code MCP Server    │
│  (AI Agent) │                │ (Python script) │               │       (Unity Editor)       │
└─────────────┘                └─────────────────┘               └────────────────────────────┘

HTTP Transport

┌─────────────┐             HTTP / SSE              ┌────────────────────────────┐
│  MCP Client │ ◄─────────────────────────────────► │   Unity Code MCP Server    │
│  (AI Agent) │                                     │       (Unity Editor)       │
└─────────────┘                                     └────────────────────────────┘

Quick start

Requirements

• Unity 2022.3 LTS or higher (tested on 2022.3.62f3 and 6000.2.7f2)
• UniTask (async/await integration): https://github.com/Cysharp/UniTask
• uv (Python package manager) for the STDIO transport: https://docs.astral.sh/uv/, RECOMMENDED

Installation

1. Install uv (if using STDIO transport, Recommended):
   • Follow instructions at https://docs.astral.sh/uv/getting-started/installation
2. Install UniTask package in your Unity project:
   • Open Unity Package Manager: Window > Package Manager
   • Click the + button and select Add package from git URL...
   • Enter Git URL

https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask

3. Install Unity Code MCP Server package:
   • Open Unity Package Manager: Window > Package Manager
   • Click the + button and select Add package from git URL...

• Enter the Git URL:

https://github.com/Signal-Loop/UnityCodeMCPServer.git?path=Assets/Plugins/UnityCodeMcpServer

4. Install Skills (Markdown files that teach your agent how to use the server's tools effectively):
   • In Unity Editor, open server settings: Tools/UnityCodeMcpServer/Show Settings
   • Scroll to the Skills section
   • Choose a target directory for skills (e.g. .github/skills/) and click Install / Update Skills

First Run

MCP client configuration

1. Open your Unity project (the STDIO server auto-starts with the Editor).
2. In Unity, run menu item: Tools/UnityCodeMcpServer/STDIO or HTTP/Print MCP Configuration to Console.
3. Copy the printed MCP configuration into your MCP client.

STDIO

Example configuration (using uv to run the bridge):

{
  "servers": {
    "unity-code-mcp-stdio": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/YOUR_USERNAME/path/to/UnityProject/Assets/Plugins/UnityCodeMcpServer/Editor/STDIO~",
        "unity-code-mcp-stdio"
      ]
    }
  }
}

Streamable HTTP

{
  "servers": {
    "unity-code-mcp-http": {
      "url": "http://127.0.0.1:3001/mcp/",
      "type": "http"
    }
  }
}

Server configuration (Unity)

1. Access (and create if necessary) settings via Tools/UnityCodeMcpServer/Show Settings.
2. Configure options:
   • Server Selection: Choose STDIO (TCP) or HTTP server for auto-start
   • Verbose Logging: Enable detailed logging for debugging

• TCP Server: Port (default: 21088), backlog, timeouts (changing the port restarts the STDIO server if running)
• HTTP Server: Port (default: 3001), session timeout, SSE keep-alive interval (changing the port restarts the HTTP server if running)

Menu commands

General

• Tools/UnityCodeMcpServer/Show Settings — Open the server settings asset in the inspector

STDIO Server (TCP)

• Tools/UnityCodeMcpServer/STDIO/Refresh Registry — Re-scan for new tools/prompts/resources
• Tools/UnityCodeMcpServer/STDIO/Restart Server — Restart the TCP server
• Tools/UnityCodeMcpServer/STDIO/Print MCP configuration to console — Log MCP client configuration for STDIO bridge

HTTP Server

• Tools/UnityCodeMcpServer/HTTP/Refresh Registry — Re-scan for new tools/prompts/resources
• Tools/UnityCodeMcpServer/HTTP/Restart Server — Restart the HTTP server
• Tools/UnityCodeMcpServer/HTTP/Log Server Status — Display current HTTP server status
• Tools/UnityCodeMcpServer/HTTP/Print MCP configuration to console — Log MCP client configuration for HTTP server

Built-in tools

execute_csharp_script_in_unity_editor

Use this tool to perform changes or automate tasks in Unity Editor by creating and executing C# scripts.
Scripts run in the Unity Editor context using Roslyn with full access to UnityEngine, UnityEditor, and any project assembly.
Perfect for creating GameObjects, modifying scenes, configuring components, or automating Unity Editor tasks.
Returns execution status, output, and any logs/errors.

**ALWAYS use `execute_csharp_script_in_unity_editor` tool for ANY Unity Editor modifications or automation tasks.**

**ALWAYS prefer `execute_csharp_script_in_unity_editor` tool to modification of Unity Yaml files.**

### When to Use This Tool (Use for ALL of these scenarios):
- Creating, modifying, or deleting GameObjects in scenes
- Adding, configuring, or removing Components
- Adjusting Transform properties (position, rotation, scale)
- Setting up UI elements and Canvas hierarchies
- Creating or modifying Prefabs
- Configuring ScriptableObject instances
- Scene management (creating, loading, switching scenes)
- Asset manipulation (importing, configuring, organizing, modifying)
- Batch operations on multiple GameObjects
- Editor window automation
- Project structure setup
- ANY task that modifies Unity Editor state

### Why This Tool is Required:
- **Direct execution**: Scripts run immediately in the Unity Editor context using Roslyn
- **Full API access**: Complete access to UnityEngine, UnityEditor, and all project assemblies
- **Immediate feedback**: Returns execution sta