Unity Code MCP Server

Search the live Unity project

Inspect active scenes, components, assets, console output, settings, Play Mode state, and runtime values from an MCP client.

Execute directly inside the Editor

Create and modify GameObjects, prefabs, ScriptableObjects, import settings, and other Unity assets by executing C# in the Editor.

Verify with runtime feedback

Run Edit Mode and Play Mode tests, enter Play Mode, simulate player input, capture screenshots, read Unity console logs, and inspect live game state after actions.

Example agent workflow: Play Pong in a closed loop by using enter_play_mode, execute_csharp_script_in_unity_editor, play_unity_game, and read_unity_console_logs to search runtime state, execute input actions, verify the result, and adapt the next move.

Real workflow example

See the full cities workflow example and transcript.

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.

enter_play_mode

Enter Unity Play Mode, pause time and return immediately after triggering the transition. Intended to be used before gameplay automation tools.

play_unity_game

Temporarily unpause time, simulate configured Input System actions, collect logs, and pause again when finished.

get_unity_game_view_window_screenshot

Capture the current Unity Game View as an image without routing screenshot capture through gameplay input calls.

exit_play_mode

Exit Unity Play Mode, unpause time, and return immediately after triggering the transition.

get_unity_info

Returns information about the current Unity Editor project and the UnityCodeMcpServer settings.

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

Architecture diagram: The Unity Code MCP Server package runs inside the Unity Editor and communicates with an external MCP client (like an LLM agent) through a file-backed STDIO bridge.

STDIO Transport

graph LR
    A["MCP Client<br/>AI Agent"] -->|STDIO| B["STDIO Bridge<br/>Python script"]
    B <-->|request/response files| C["Unity Code MCP Server<br/>Unity Editor"]

    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5

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 bundled STDIO bridge: https://docs.astral.sh/uv/.

Installation

Install uv:
- Follow instructions at https://docs.astral.sh/uv/getting-started/installation
Install UniTask in your Unity project. Open Window > Package Manager, click the + button, select Add package from git URL..., and enter:

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

Install Unity Code MCP Server from Unity Package Manager. Open Window > Package Manager, click the + button, select Add package from git URL..., and enter:

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

Configure the skill install location. Open Tools/UnityCodeMcpServer/Show or Create Settings, scroll to the Skills section, and confirm or change the install directory. By default, first-time installs target .agents/skills/. Skills are installed and updated automatically when the package is installed or updated.

First Run

MCP client configuration

Open your Unity project. Unity auto-starts the file-backed transport and watches .unityCodeMcpServer/messages in the project root.
Configure your MCP client to run the bundled STDIO bridge.

STDIO

Example configuration (using uv to run the bridge):

The unity-code-mcp-stdio bridge forwards STDIO traffic to Unity through .unityCodeMcpServer/messages.

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

Server configuration (Unity)

Access the settings via Tools/UnityCodeMcpServer/Show or Create Settings.
Configure Verbose Logging for detailed diagnostics and optionally set Input Actions Asset for play_unity_game.

The file-backed transport exchanges request and response files through .unityCodeMcpServer/messages in the Unity project root.

Menu commands

General

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

Agent skills

Unity Code MCP Server ships a set of AI agent skill files (Markdown documents that teach your agent how to use the server's tools effectively). These skills are installed automatically into the configured target directory whenever the package is installed or updated.

Installing skills

Open the server settings: Tools/UnityCodeMcpServer/Show or Create Settings.
Scroll to the Skills section.
Choose the install directory from the dropdown:

GitHub targets .github/skills/
Claude targets .claude/skills/
Agents targets .agents/skills/
Custom shows a folder picker so you can select any directory

The inspector shows the currently selected target directory label so you can verify exactly where skills will be copied.
Package install and update runs copy the skills automatically.

Only new or changed .md files are copied. Files that are already up to date (matching content hash) are skipped.

Included skills

Skill	Description
`executing-csharp-scripts-in-unity-editor`	Teaches the agent when and how to use `execute_csharp_script_in_unity_editor`, `read_unity_console_logs`, and `run_unity_tests` together as a reliable pipeline. Covers forbidden patterns, debugging loops, and common scripting patterns.
`unity-game-player`	Teaches the agent how to play and test Unity games in a closed loop using `enter_play_mode`, `play_unity_game`, `execute_csharp_script_in_unity_editor`, `read_unity_console_logs`, and `exit_play_mode`. Covers scene discovery, math-based action timing, and adaptive re-sensing.

Extending (adding tools)

Add Tools, Prompts, Resources, or Async Tools by implementing the relevant interfaces (ITool, IToolAsync, IPrompt, IResource) anywhere in your codebase. The server will automatically detect and register them.

Synchronous tool

using System.Collections.Generic;
using System.Text.Json;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;

public class EchoTool : ITool
{
    public string Name => "echo";

    public string Description => "Echoes the input text back to the caller";

    public JsonElement InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                }
            },
            ""required"": [""text""]
        }");

    public ToolsCallResult Execute(JsonElement arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");

        return ToolsCallResult.TextResult($"Echo: {text}");
    }
}

Asynchronous tool

using System.Collections.Generic;
using System.Text.Json;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;
using Cysharp.Threading.Tasks;

public class DelayedEchoTool : IToolAsync
{
    public string Name => "delayed_echo";

    public string Description => "Echoes the input text after a specified delay (demonstrates async tool)";

    public JsonElement InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                },
                ""delayMs"": {
                    ""type"": ""integer"",
                    ""description"": ""Delay in milliseconds before echoing"",
                    ""default"": 1000
                }
            },
            ""required"": [""text""]
        }");

    public async UniTask<ToolsCallResult> ExecuteAsync(JsonElement arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");
        var delayMs = arguments.GetIntOrDefault("delayMs", 1000);

        await UniTask.Delay(delayMs);

        return ToolsCallResult.TextResult($"Delayed Echo (after {delayMs}ms): {text}");
    }
}

Script execution context

By default, script execution context includes following assemblies:

Assembly-CSharp
Assembly-CSharp-Editor
System.Core
UnityEngine.CoreModule
UnityEditor.CoreModule

Unity Code MCP Server settings (Assets/Plugins/UnityCodeMcpServer/Editor/Resources/UnityCodeMcpServerSettings.asset) allow configuring additional assemblies to include in the script execution context. This is useful if your project has assemblies that your generated scripts need to reference.

To add additional assemblies use settings 'Additional Assemblies' section.

STDIO bridge

See the bridge docs at README_STDIO.md.

Testing

Unity tests are in Assets/Tests/ and can be run via the Unity Test Runner.

Known Issues

GUID conflicts with existing dll files in the project

Unity Code MCP Server includes dll files in its package. If those files are already present in your project, you may see GUID conflicts. In our test cases it does not cause any issues, but if you encounter problems, please fill issue: Issues. Removing duplicate dlls from your project may resolve the conflicts.

GUID [eb9c83041c7a89c46bb6e20eab4484df] for asset 'Packages/com.signal-loop.unitycodemcpserver/Editor/Bin/Microsoft.CodeAnalysis.CSharp.dll' conflicts with:
  '[Path to dll file in your project]/Microsoft.CodeAnalysis.CSharp.dll' (current owner)
We can't assign a new GUID because the asset is in an immutable folder. The asset will be ignored.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 252 Commits
.agents/skills		.agents/skills
.unityCodeMcpServer		.unityCodeMcpServer
Assets		Assets
Dev		Dev
Packages		Packages
ProjectSettings		ProjectSettings
docs/superpowers		docs/superpowers
images		images
.editorconfig		.editorconfig
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
README_STDIO.md		README_STDIO.md
UnityCodeMcpServer.slnx		UnityCodeMcpServer.slnx

Folders and files

Latest commit

History

Repository files navigation

Unity Code MCP Server

Search the live Unity project

Execute directly inside the Editor

Verify with runtime feedback

Real workflow example

Table of contents

Tools

execute_csharp_script_in_unity_editor

read_unity_console_logs

run_unity_tests

enter_play_mode

play_unity_game

get_unity_game_view_window_screenshot

exit_play_mode

get_unity_info

Security considerations

Architecture

STDIO Transport

Quick start

Requirements

Installation

First Run

MCP client configuration

STDIO

Server configuration (Unity)

Menu commands

General

Agent skills

Installing skills

Included skills

Extending (adding tools)

Synchronous tool

Asynchronous tool

Script execution context

STDIO bridge

Testing

Known Issues

GUID conflicts with existing dll files in the project

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages