Home

Relevant source files

The following files were used as context for generating this wiki page:

• Packages/src/ARCHITECTURE.md
• Packages/src/README.md
• README.md
• Packages/src/TOOL_REFERENCE.md
• Packages/src/TypeScriptServer~/README.md
• SECURITY.md
• Packages/src/Cli~/src/tests/skills-manager.test.ts
• Packages/src/Cli~/scripts/generate-bundled-skills.ts
• Packages/src/Cli~/src/tests/cli-e2e.test.ts
• CLAUDE.md
• AGENTS.md
• Packages/src/ARCHITECTURE_ja.md
• Packages/src/TypeScriptServer~/package.json
• Assets/Tests/Editor/DynamicCodeToolTests/WrapCodeWithUsingStatementsAdvancedTests.cs

uLoopMCP is a Model Context Protocol (MCP) server designed to let AI agents compile, test, and operate Unity projects from popular LLM-powered development tools like Claude Code, Cursor, and VSCode. The core concept is to provide a "self-hosted development loop" where an AI can autonomously perform tasks that humans typically handle manually, such as compiling, running tests, checking logs, and manipulating the Unity Editor.

This is achieved by exposing a rich set of tools that LLMs can orchestrate. These tools allow an AI to not only manage the development lifecycle (compile, test, analyze, fix) but also to directly interact with the Unity Editor for tasks like scene manipulation, object inspection, and dynamic code execution. The system is designed for easy setup and extensibility, allowing developers to add project-specific tools for custom automation.

Sources: README.md:15-24, Packages/src/ARCHITECTURE.md:10-14

System Architecture

The uLoopMCP system is composed of three main components that communicate to bridge the gap between LLM clients and the Unity Editor.

• MCP Clients: LLM-powered tools (e.g., Claude Code, Cursor) that consume the MCP protocol.
• TypeScript Server: A Node.js process that acts as the MCP protocol server. It features a Domain-Driven Design (DDD) architecture and manages communication between the clients and Unity.
• Unity Editor: A C# TCP server integrated into the Unity Editor. It exposes the tool system, manages security, and executes commands within the Unity environment.

Sources: Packages/src/ARCHITECTURE.md:10-14

High-Level Communication Flow

The diagram below illustrates the communication flow between the components. LLM clients send MCP requests to the TypeScript server, which then translates them into JSON-RPC calls over TCP to the Unity Editor.

Installation and Quickstart

Prerequisites

• Unity 2022.3 or later
• Node.js 22.0 or later

Sources: README.md:403-405

Installation

You can install uLoopMCP into your Unity project via the Unity Package Manager using one of two methods:

1. Add package from git URL:

   https://github.com/hatayama/uLoopMCP.git?path=/Packages/src
   

2. Via OpenUPM (Recommended): Add the OpenUPM scoped registry to your Project Settings.
   • Name: OpenUPM
   • URL: https://package.openupm.com
   • Scope(s): io.github.hatayama.uloopmcp

Sources: README.md:65-68, README.md:410-425

Quickstart

1. Install the package using one of the methods above.
2. In the Unity Editor, open Window > uLoopMCP.
3. Press the Start Server button to launch the MCP server.
4. In the LLM Tool Settings section of the window, select your target LLM tool (e.g., Cursor) and press the Configure {Tool name} button to automatically set up the connection.
5. Enable the uLoopMCP server in your LLM tool's settings.

Sources: README.md:64-77

Key Features & Tools

uLoopMCP provides a suite of tools to enable AI-driven development. These can be broadly categorized into development loop tools and editor automation tools. For a full specification of all tool parameters and responses, see the Tool Reference.

Sources: README.md:86, Packages/src/TOOL_REFERENCE.md

Tool Name	Description	Category
compile	Executes AssetDatabase.Refresh() and compiles the project, returning errors and warnings.	Development Loop
get-logs	Retrieves logs from the Unity Console with filtering and search capabilities.	Development Loop
run-tests	Executes EditMode or PlayMode tests via the Unity Test Runner and returns results.	Development Loop
clear-console	Clears all logs from the Unity Console.	Editor Automation
unity-search	Performs a project-wide search using the UnitySearch API.	Editor Discovery
get-provider-details	Retrieves available search providers for unity-search.	Editor Discovery
get-menu-items	Retrieves a list of all MenuItem attributes defined in the project.	Editor Discovery
execute-menu-item	Executes a menu item by its path (e.g., "GameObject/Create Empty").	Editor Automation
find-game-objects	Searches for GameObjects in the current scene based on various criteria.	Editor Discovery
get-hierarchy	Exports the active scene hierarchy to a JSON file to analyze scene structure.	Editor Discovery
focus-window	Brings the Unity Editor window to the foreground (macOS & Windows).	Editor Automation
capture-window	Captures any EditorWindow as a PNG image.	Editor Automation
control-play-mode	Starts, stops, or pauses the Unity Editor's Play Mode.	Editor Automation
execute-dynamic-code	Dynamically executes C# code within the Unity Editor, with security controls.	Editor Automation

Sources: README.md:87-234, Packages/src/TOOL_REFERENCE.md:12-282

CLI Tool (uloop)

uLoopMCP includes a standalone CLI tool, uloop, which provides the same functionality as the MCP server but is designed to work with "Skills-compatible" LLM tools like Claude Code.

Benefits of the CLI:

• No MCP configuration required: LLM tools use "Skills" to automatically invoke the CLI.
• Context-efficient: Does not consume LLM context in the same way MCP does.
• Operate multiple Unity instances: Use the --port option to target different running Unity projects.

Sources: README.md:300-313

CLI Quick Start

1. Install the CLI globally:

   npm install -g uloop-cli
   

2. Install the skills into your project:

   # For Claude Code (project-level)
   uloop skills install --claude
   

Once skills are installed, LLM tools can automatically use commands like /uloop-compile and /uloop-run-tests in response to natural language instructions.

Sources: README.md:315-327

Direct CLI Usage

You can also invoke the tools directly from your terminal.

# Sync tool definitions from the running Unity instance
uloop sync

# Execute compilation
uloop compile

# Get the last 10 logs
uloop get-logs --max-count 10

# Run all tests
uloop run-tests --filter-type all

Sources: README.md:358-375, Packages/src/Cli~/src/tests/cli-e2e.test.ts

Security

Security is a critical consideration, especially for tools that can execute code. uLoopMCP implements several security measures.

Sources: SECURITY.md:24-27

Security Settings

Several powerful tools are disabled by default and must be enabled via the Window > uLoopMCP editor window:

• Allow Tests Execution: Enables the run-tests tool.
• Allow Menu Item Execution: Enables the execute-menu-item tool.
• Allow Third Party Tools: Enables custom tools developed for the project.

Sources: README.md:239-246

Dynamic Code Security (execute-dynamic-code)

The execute-dynamic-code tool has a three-tier security model to control its capabilities.

Level	Name	Description
0	Disabled	All dynamic code execution is blocked.
1	Restricted	(Recommended) Allows most Unity APIs and standard libraries but blocks dangerous operations like file deletion, network access, and process execution.
2	FullAccess	No restrictions. All APIs are accessible. Use only with trusted code.

Sources: README.md:210-234, SECURITY.md:29-30

When using AI-driven code generation, it is strongly recommended to run in a sandboxed environment and use the Restricted security level.

Sources: README.md:252-254, SECURITY.md:46-48

Extension Development

uLoopMCP is designed to be extensible, allowing teams to create project-specific tools and skills.

Creating a Custom Tool

You can create a custom tool by defining schema, response, and tool classes in C#. The [McpTool] attribute ensures the tool is automatically discovered and registered. All custom tools run on Unity's main thread, making Unity API calls safe.

A basic custom tool implementation follows this structure:

// 1. Define parameters
public class MyCustomSchema : BaseToolSchema
{
    [Description("Parameter description")]
    public string MyParameter { get; set; }
}

// 2. Define response
public class MyCustomResponse : BaseToolResponse
{
    public string Result { get; set; }
}

// 3. Implement the tool
[McpTool(Description = "Description of my custom tool")]
public class MyCustomTool : AbstractUnityTool<MyCustomSchema, MyCustomResponse>
{
    public override string ToolName => "my-custom-tool";
    
    protected override Task<MyCustomResponse> ExecuteAsync(MyCustomSchema parameters, CancellationToken cancellationToken)
    {
        // ... custom logic ...
        return Task.FromResult(new MyCustomResponse { Result = "Success" });
    }
}

To be used, custom tools require Allow Third Party Tools to be enabled in the Security Settings.

Sources: README.md:428-490

Creating a Custom Skill

To make a custom tool discoverable by the uloop CLI and Skills-compatible LLMs, create a SKILL.md file in the same directory as your tool's C# script. The file uses YAML frontmatter to define the skill's name and description.

---
name: uloop-my-custom-tool
description: Description of what the tool does and when to use it.
---

# uloop my-custom-tool

Detailed documentation for the tool...

After creating the file, run uloop skills install to make it available to your LLM tools. The CLI automatically scans Assets/**/Editor/, Packages/*/Editor/, and Library/PackageCache/*/Editor/ for SKILL.md files.

Sources: README.md:492-519, Packages/src/Cli~/scripts/generate-bundled-skills.ts:10-14, Packages/src/Cli~/src/tests/skills-manager.test.ts:10-21