Concept

[日本語](/Packages/src/README_ja.md)

[![Unity](https://img.shields.io/badge/Unity-2022.3+-red.svg)](https://unity3d.com/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)<br>
![ClaudeCode](https://img.shields.io/badge/Claude_Code-555?logo=claude)
![Cursor](https://img.shields.io/badge/Cursor-111?logo=Cursor)
![OpenAICodex](https://img.shields.io/badge/OpenAI_Codex-111?logo=openai)
![GoogleGemini](https://img.shields.io/badge/Google_Gemini-111?logo=googlegemini)
![GitHubCopilot](https://img.shields.io/badge/GitHub_Copilot-111?logo=githubcopilot)
![Windsurf](https://img.shields.io/badge/Windsurf-111?logo=Windsurf)

<h1 align="center">
    <img width="500" alt="uLoopMCP" src="https://github.com/user-attachments/assets/a8b53cca-5444-445d-aa39-9024d41763e6" />  
</h1>

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.

# Concept
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`.**

https://github.com/user-attachments/assets/569a2110-7351-4cf3-8281-3a83fe181817

# Features
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.
6. Standalone CLI tool `uloop` provided. **No MCP configuration required—just install Skills and LLM tools will automatically operate Unity**. 14 bundled Skills enable LLM tools to handle compilation, test execution, log retrieval, and more. ([Details](#cli-tool-uloop))

# Example Use Cases
- 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.

## Quickstart
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](#installation) section for details).
2. In Unity, open `Window > uLoopMCP` and press the `Start Server` button to launch the MCP server.
<div align="center">
<img width="800" height="495" alt="uloopmcp" src="https://github.com/user-attachments/assets/08053248-7f0c-4618-8d1f-7e0560341548" />
</div>

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.”

# Key Features
## Development Loop Tools
#### 1. compile - Execute Compilation
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, anal

... (truncated)