Installation and Setup

Relevant source files

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

• README.md
• Packages/src/README.md
• Packages/src/ARCHITECTURE.md
• Packages/src/Cli~/src/cli.ts
• Packages/src/Editor/Config/CodexTomlConfigService.cs
• Packages/src/TypeScriptServer~/package.json
• SECURITY.md
• Packages/src/Cli~/scripts/generate-bundled-skills.ts

uLoopMCP is a server that allows AI agents to compile, test, and operate a Unity project from popular LLM tools like Cursor, Claude Code, and others. It exposes common development tasks—compiling, running tests, checking logs, and editing scenes—as tools that an LLM can orchestrate, enabling an autonomous development loop within existing Unity projects.

This guide covers the necessary prerequisites, installation methods, and configuration steps to get uLoopMCP running in your Unity project and connected to your preferred LLM tool. It details two primary integration paths: the traditional MCP server configuration and the more streamlined uloop CLI with Skills. For more architectural details, see the Architecture Overview.

Sources: README.md:15-25, Packages/src/ARCHITECTURE.md:11-17

Prerequisites

Before installing uLoopMCP, ensure your development environment meets the following requirements:

Software	Version	Notes
Unity	2022.3 or later	Required for the core package functionality.
Node.js	22.0 or later	Required for the MCP TypeScript server and the uloop CLI tool.

Sources: README.md:522-526, Packages/src/TypeScriptServer~/package.json:4-5

Package Installation

There are two recommended methods for installing the uLoopMCP package into your Unity project.

This diagram shows the two installation paths available for the Unity package.

Method 1: Unity Package Manager (from Git URL)

This method adds the package directly from the GitHub repository.

1. In the Unity Editor, open Window > Package Manager.
2. Click the + button in the top-left corner.
3. Select "Add package from git URL...".
4. Enter the following URL:

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

Sources: README.md:530-536

Method 2: OpenUPM (Recommended)

This method uses a scoped registry, which makes it easier to manage package updates.

1. In the Unity Editor, open Project Settings > Package Manager.
2. Add a new entry to the Scoped Registries list with the following details:
   • Name: OpenUPM
   • URL: https://package.openupm.com
   • Scope(s): io.github.hatayama.uloopmcp
3. Open the Package Manager window, select "My Registries", and install uLoopMCP from the list.

Sources: README.md:538-546

Initial Server Setup

Once the package is installed, you must start the uLoopMCP server from within the Unity Editor. This server acts as a bridge between your Unity project and the LLM tool.

This flowchart illustrates the steps to start the server and configure the LLM tool connection.

1. In the Unity Editor, navigate to Window > uLoopMCP to open the control panel.
2. Click the Start Server button. The server will launch, and the status will update to show the active port number. uLoopMCP automatically assigns an unused port to support multiple Unity instances.
3. In the LLM Tool Settings section, select your target LLM tool (e.g., Cursor) from the dropdown menu.
4. Click the Configure {Tool name} button. This action automatically updates the necessary configuration files for the selected tool to establish a connection.

Sources: README.md:65-71, README.md:315-318

Manual LLM Tool Configuration

In most cases, automatic configuration is sufficient. However, if manual setup is required, you can edit the tool's configuration file (e.g., ~/.cursor/mcp.json for Cursor or ~/.codex/config.toml for Codex) to define the uLoopMCP server.

The configuration points to a server.bundle.js file, which is the entry point for the TypeScript-based MCP server. The UNITY_TCP_PORT environment variable tells this server which port the Unity Editor is listening on.

The following sequence diagram shows how the auto-configuration process works.

Example mcp.json (for Cursor):

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

Sources: README.md:334-346

The CodexTomlConfigService.cs class handles the logic for reading and writing the config.toml file for Codex, using regular expressions to find and update the [mcp_servers.uLoopMCP] section.

Sources: Packages/src/Editor/Config/CodexTomlConfigService.cs

uloop CLI and Skills Setup

As an alternative to MCP server configuration, uLoopMCP provides a standalone Command Line Interface (CLI) tool named uloop. This approach integrates with LLM tools via a "Skills" system, which offers several benefits:

• No manual MCP configuration is needed.
• It is more context-efficient for the LLM.
• It can operate multiple Unity instances from a single agent using the --port flag.

CLI Installation

Install the uloop CLI globally using npm.

npm install -g uloop-cli

Sources: README.md:374-376

Skills Installation

After installing the CLI, install the bundled skills into your project. This makes the tools discoverable by Skills-compatible LLM tools like Claude Code.

# Install skills for Claude Code at the project level
uloop skills install --claude

# Or, install skills globally
uloop skills install --claude --global

Sources: README.md:379-385

Once installed, the LLM tool can automatically invoke uloop commands to interact with Unity based on your instructions. The generate-bundled-skills.ts script is responsible for discovering all SKILL.md files within the project and bundling them into bundled-skills.ts for the CLI to use.

Your Instruction	Skill Used by LLM Tools
"Fix the compile errors"	/uloop-compile
"Run the tests and tell me why they failed"	/uloop-run-tests + /uloop-get-logs
"Check the scene hierarchy"	/uloop-get-hierarchy
"Search for prefabs"	/uloop-unity-search

Sources: README.md:389-399, Packages/src/Cli~/scripts/generate-bundled-skills.ts:1-6

Shell Completion (Optional)

To improve usability, you can install shell completion scripts for Bash, Zsh, or PowerShell.

# Auto-detect shell and install completion
uloop completion --install

The cli.ts file contains the logic for detecting the shell and providing the correct completion script.

Sources: README.md:424-432, Packages/src/Cli~/src/cli.ts:245-263

Claude Code Sandbox Configuration

If using the uloop CLI with Claude Code in sandbox mode, you must allow localhost network connections. Add the following to your project's .claude/settings.local.json:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowLocalBinding": true
    }
  }
}

Sources: README.md:447-459

Security Configuration

For security, several powerful tools are disabled by default. You must enable them manually in the uLoopMCP window.

Setting	Description	Default
Allow Tests Execution	Enables the run-tests tool.	Disabled
Allow Menu Item Execution	Enables the execute-menu-item tool.	Disabled
Allow Third Party Tools	Enables custom tools developed for the project.	Disabled

The execute-dynamic-code tool has its own tiered security levels:

Level	Name	Description
0	Disabled	Code execution is completely disabled. (Safest)
1	Restricted	Allows most Unity APIs but blocks dangerous operations like file deletion, network access, and process execution. (Recommended)
2	FullAccess	All APIs are available with no restrictions. Use only with trusted code.

It is strongly recommended to run AI-driven development in a sandboxed environment to mitigate security risks.

Sources: README.md:251-277, SECURITY.md:29-32

Special Setup for execute-dynamic-code

The execute-dynamic-code tool requires an additional package to compile C# code at runtime.

1. Follow the steps in Method 2: OpenUPM to add a scoped registry, but use the following settings:
   • Name: OpenUPM
   • URL: https://package.openupm.com
   • Scope(s): org.nuget
2. In the Package Manager window, find and install Microsoft.CodeAnalysis.CSharp from the OpenUPM registry.

Sources: README.md:204-225