日本語

Let an AI agent compile, test, and operate your Unity project from popular LLM tools.

Designed to keep AI-driven development loops running autonomously inside your existing Unity projects.

uLoopMCP is an MCP server designed so that AI can drive your Unity project forward with minimal human intervention. Tasks that humans typically handle manually—compiling, running the Test Runner, checking logs, and editing scenes in the Editor—are exposed as tools that LLMs can orchestrate.

uLoopMCP is built around two core ideas:

1. Provide a “self-hosted development loop” where an AI can repeatedly compile, run tests, inspect logs, and fix issues using tools like compile, run-tests, get-logs, and clear-console.
2. Allow AI to operate the Unity Editor itself—creating objects, calling menu items, and inspecting scenes—via tools like execute-dynamic-code and execute-menu-item.

1. Bundle of tools to let AI run the full loop (compile → test → log analysis → fix → repeat) on a Unity project.
2. execute-dynamic-code at the core, enabling rich Unity Editor automation: menu execution, scene exploration, GameObject manipulation, and more.
3. Easy setup from Unity Package Manager and a few clicks to connect from LLM tools (Cursor, Claude Code, GitHub Copilot, Windsurf, etc.).
4. Type-safe extension model for adding project-specific MCP tools that AI can implement and iterate on for you.
5. Log and hierarchy data can be exported to files to avoid burning LLM context on large payloads.

• Let an AI keep fixing your project until compilation passes and all tests go green.
• Ask the AI to fix bugs or refactor existing code, and verify results using compile / test runner execution / log retrieval.
• After verification, enter Play Mode using MenuItem execution or compile-free C# code execution, then bring Unity Editor to the foreground with Unity window focus.
• Have the AI inspect large numbers of Prefabs / GameObjects using Hierarchy inspection, Unity Search, and compile-free C# code execution for bulk parameter adjustments or scene structure organization.
• Build team-specific MCP tools for custom checks and automated refactors, and call them from your LLM environment.

1. Install the uLoopMCP package into your Unity project.

• In Unity Package Manager, choose "Add package from git URL" and use:
  https://github.com/hatayama/uLoopMCP.git?path=/Packages/src
• Alternatively, you can use the OpenUPM scoped registry (see the Installation section for details).

2. In Unity, open Window > uLoopMCP and press the Start Server button to launch the MCP server.

3. Select your target tool from the dropdown in LLM Tool Settings, then press the "Configure {Tool name}" button.
4. In your LLM tool (Cursor, Claude Code, Codex, Gemini, etc.), enable uLoopMCP as an MCP server.
5. For example, if you give instructions like the following, the AI will start running an autonomous development loop:

• “Fix this project until compile reports no errors, using the compile tool as needed.”
• “Run tests in uLoopMCP.Tests.Editor with run-tests and keep updating the code until all tests pass.”
• “Use execute-dynamic-code to create a sample scene with 10 cubes and adjust the camera so all cubes are visible.”

Performs AssetDatabase.Refresh() and then compiles, returning the results. Can detect errors and warnings that built-in linters cannot find.
You can choose between incremental compilation and forced full compilation.

→ Execute compile, analyze error and warning content
→ Automatically fix relevant files
→ Verify with compile again

Filter by LogType or search target string with advanced search capabilities. You can also choose whether to include stacktrace. This allows you to retrieve logs while keeping the context small. MaxCount behavior: Returns the latest logs (tail-like behavior). When MaxCount=10, returns the most recent 10 logs. Advanced Search Features:

• Regular Expression Support: Use UseRegex: true for powerful pattern matching
• Stack Trace Search: Use SearchInStackTrace: true to search within stack traces

→ get-logs (LogType: Error, SearchText: "NullReference", MaxCount: 10)
→ get-logs (LogType: All, SearchText: "(?i).*error.*", UseRegex: true, MaxCount: 20)
→ get-logs (LogType: All, SearchText: "MyClass", SearchInStackTrace: true, MaxCount: 50)
→ Identify cause from stacktrace, fix relevant code

Executes Unity Test Runner and retrieves test results. You can set conditions with FilterType and FilterValue.

• FilterType: all (all tests), exact (individual test method name), regex (class name or namespace), assembly (assembly name)
• FilterValue: Value according to filter type (class name, namespace, etc.)
  Test results can be output as xml. The output path is returned so AI can read it.
  This is also a strategy to avoid consuming context.

→ run-tests (FilterType: exact, FilterValue: "io.github.hatayama.uLoopMCP.ConsoleLogRetrieverTests.GetAllLogs_WithMaskAllOff_StillReturnsAllLogs")
→ Check failed tests, fix implementation to pass tests

Clear logs that become noise during log searches.

→ clear-console
→ Start new debug session

You can use UnitySearch.

→ unity-search (SearchQuery: "*.prefab")
→ List prefabs matching specific conditions
→ Identify problematic prefabs

Retrieve search providers offered by UnitySearch.

→ Understand each provider's capabilities, choose optimal search method

Retrieve menu items defined with [MenuItem("xxx")] attribute. Can filter by string specification.

Execute menu items defined with [MenuItem("xxx")] attribute.

→ Execute project-specific tools
→ Check results with get-logs

Retrieve objects and examine component parameters.

→ find-game-objects (RequiredComponents: ["Camera"])
→ Investigate Camera component parameters

Retrieve information about the currently active Hierarchy in nested JSON format. Works at runtime as well. Automatic File Export: Retrieved hierarchy data is always saved as JSON in {project_root}/uLoopMCPOutputs/HierarchyResults/ directory. The MCP response only returns the file path, minimizing token consumption even for large datasets.

→ Understand parent-child relationships between GameObjects, discover and fix structural issues
→ Regardless of scene size, hierarchy data is saved to a file and the path is returned instead of raw JSON

Ensures the Unity Editor window associated with the active MCP session becomes the foreground application on macOS and Windows Editor builds.
Great for keeping visual feedback in sync after other apps steal focus. (Linux is currently unsupported.)

Execute C# code dynamically within Unity Editor.

⚠️ Important Prerequisites
To use this tool, you must install the Microsoft.CodeAnalysis.CSharp package using OpenUPM NuGet.

Name: OpenUPM
URL: https://package.openupm.com
Scope(s): org.nuget

Async support:

• You can write await in your snippet (Task/ValueTask/UniTask and any awaitable type)
• Cancellation is propagated when you pass a CancellationToken to the tool

Security Level Support: Implements 3-tier security control to progressively restrict executable code:

• Level 0 - Disabled

  • No compilation or execution allowed

• Level 1 - Restricted 【Recommended Setting】

  • All Unity APIs and .NET standard libraries are generally available
  • User-defined assemblies (Assembly-CSharp, etc.) are also accessible
  • Only pinpoint blocking of security-critical operations:
    • File deletion: File.Delete, Directory.Delete, FileUtil.DeleteFileOrDirectory
    • File writing: File.WriteAllText, File.WriteAllBytes, File.Replace
    • Network communication: All HttpClient, WebClient, WebRequest, Socket, TcpClient operations
    • Process execution: Process.Start, Process.Kill
    • Dynamic code execution: Assembly.Load*, Type.InvokeMember, Activator.CreateComInstanceFrom
    • Thread manipulation: Direct Thread, Task manipulation
    • Registry operations: All Microsoft.Win32 namespace operations
  • Safe operations are allowed:
    • File reading (File.ReadAllText, File.Exists, etc.)
    • Path operations (all Path.* operations)
    • Information retrieval (Assembly.GetExecutingAssembly, Type.GetType, etc.)
  • Use cases: Normal Unity development, automation with safety assurance

• Level 2 - FullAccess

  • All assemblies are accessible (no restrictions)
  • ⚠️ Warning: Security risks exist, use only with trusted code

→ execute-dynamic-code (Code: "GameObject cube = GameObject.CreatePrimitive(PrimitiveType.Cube); return \"Cube created\";")
→ Rapid prototype verification, batch processing automation
→ Unity API usage restricted according to security level

For detailed specifications of all tools (parameters, responses, examples), see TOOL_REFERENCE.md.

1. Select Window > uLoopMCP. A dedicated window will open, so press the "Start Server" button.

2. Next, select the target IDE in the LLM Tool Settings section. Press the yellow "Configure {LLM Tool Name}" button to automatically connect to the IDE.

3. IDE Connection Verification

• For example, with Cursor, check the Tools & MCP in the settings page and find uLoopMCP. Click the toggle to enable MCP. If a red circle appears, restart Cursor.

{
  "mcpServers": {
    "uLoopMCP": {
      "command": "node",
      "args": [
        "[Unity Package Path]/TypeScriptServer~/dist/server.bundle.js"
      ],
      "env": {
        "UNITY_TCP_PORT": "{port}"
      }
    }
  }
}

5. Multiple Unity Instance Support

1. Open Unity Editor
2. Open Window > Package Manager
3. Click the "+" button
4. Select "Add package from git URL"
5. Enter the following URL:

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

1. Open Project Settings window and go to Package Manager page
2. Add the following entry to the Scoped Registries list:

Name: OpenUPM
URL: https://package.openupm.com
Scope(s): io.github.hatayama.uloopmcp

3. Open Package Manager window and select OpenUPM in the My Registries section. uLoopMCP will be displayed.

uLoopMCP enables efficient development of project-specific MCP tools without requiring changes to the core package.
The type-safe design allows for reliable custom tool implementation in minimal time. (If you ask AI, they should be able to make it for you soon ✨)

using System.ComponentModel;

public class MyCustomSchema : BaseToolSchema
{
    [Description("Parameter description")]
    public string MyParameter { get; set; } = "default_value";
    
    [Description("Example enum parameter")]
    public MyEnum EnumParameter { get; set; } = MyEnum.Option1;
}

public enum MyEnum
{
    Option1 = 0,
    Option2 = 1,
    Option3 = 2
}

public class MyCustomResponse : BaseToolResponse
{
    public string Result { get; set; }
    public bool Success { get; set; }
    
    public MyCustomResponse(string result, bool success)
    {
        Result = result;
        Success = success;
    }
    
    // Required parameterless constructor
    public MyCustomResponse() { }
}

using System.Threading;
using System.Threading.Tasks;

[McpTool(Description = "Description of my custom tool")]  // ← Auto-registered with this attribute
public class MyCustomTool : AbstractUnityTool<MyCustomSchema, MyCustomResponse>
{
    public override string ToolName => "my-custom-tool";
    
    // Executed on main thread
    protected override Task<MyCustomResponse> ExecuteAsync(MyCustomSchema parameters, CancellationToken cancellationToken)
    {
        // Type-safe parameter access
        string param = parameters.MyParameter;
        MyEnum enumValue = parameters.EnumParameter;
        
        // Check for cancellation before long-running operations
        cancellationToken.ThrowIfCancellationRequested();
        
        // Implement custom logic here
        string result = ProcessCustomLogic(param, enumValue);
        bool success = !string.IsNullOrEmpty(result);
        
        // For long-running operations, periodically check for cancellation
        // cancellationToken.ThrowIfCancellationRequested();
        
        return Task.FromResult(new MyCustomResponse(result, success));
    }
    
    private string ProcessCustomLogic(string input, MyEnum enumValue)
    {
        // Implement custom logic
        return $"Processed '{input}' with enum '{enumValue}'";
    }
}

MIT License