UniCortex

A toolkit for controlling Unity Editor externally via REST API, MCP (Model Context Protocol), and CLI.

Primarily designed for AI agents (Claude Code, Codex CLI, etc.) to operate Unity Editor through MCP. Also provides a CLI tool for terminal-based control.

• Unity 2022.3 or later
• .NET 10 SDK (for MCP server and CLI)

Add via Unity Package Manager using a Git URL:

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

https://github.com/VeyronSakai/UniCortex.git

Add the following MCP server configuration to your MCP client's settings file (e.g., .mcp.json, claude_desktop_config.json, etc.). Refer to your client's documentation for the exact configuration location.

{
  "mcpServers": {
    "Unity": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "dotnet run --project ${UNICORTEX_PROJECT_PATH}/Library/PackageCache/com.veyron-sakai.uni-cortex@*/Tools~/UniCortex.Mcp/"],
      "env": {
        "UNICORTEX_PROJECT_PATH": "/path/to/your/unity/project"
      }
    }
  }
}

Replace /path/to/your/unity/project with the absolute path of your Unity project. After saving the configuration, restart the client to apply the changes.

The MCP server reads the port number from Library/UniCortex/config.json (written automatically when Unity Editor starts) and connects to the HTTP server.

No pre-build or tool installation is required. The MCP server is built and started automatically via dotnet run.

Alternatively, you can specify the URL directly via the UNICORTEX_URL environment variable (takes priority over UNICORTEX_PROJECT_PATH):

{
  "mcpServers": {
    "Unity": {
      "type": "stdio",
      "command": "/bin/bash",
      "args": ["-c", "dotnet run --project ${UNICORTEX_PROJECT_PATH}/Library/PackageCache/com.veyron-sakai.uni-cortex@*/Tools~/UniCortex.Mcp/"],
      "env": {
        "UNICORTEX_PROJECT_PATH": "/path/to/your/unity/project",
        "UNICORTEX_URL": "http://localhost:12345"
      }
    }
  }
}

UniCortex also provides a CLI tool for controlling Unity Editor from the terminal:

# Set the Unity project path
export UNICORTEX_PROJECT_PATH="/path/to/your/unity/project"

# Run CLI commands
dotnet run --project "${UNICORTEX_PROJECT_PATH}/Library/PackageCache/com.veyron-sakai.uni-cortex@*/Tools~/UniCortex.Cli/" -- editor ping
dotnet run --project "${UNICORTEX_PROJECT_PATH}/Library/PackageCache/com.veyron-sakai.uni-cortex@*/Tools~/UniCortex.Cli/" -- scene hierarchy
dotnet run --project "${UNICORTEX_PROJECT_PATH}/Library/PackageCache/com.veyron-sakai.uni-cortex@*/Tools~/UniCortex.Cli/" -- gameobject find "t:Camera"

graph LR
    Agent["AI Agent"]
    MCP["UniCortex.Mcp<br/>.NET 10"]
    CLI["UniCortex.Cli<br/>.NET 10"]
    Unity["Unity Editor<br/>HTTP Server"]

    Agent -- "MCP / stdio" --> MCP
    Agent -- "CLI" --> CLI
    MCP -- "HTTP" --> Unity
    CLI -- "HTTP" --> Unity

• Unity Editor side: C# HttpListener HTTP server embedded in the Editor
• Shared Core: UniCortex.Core — service layer and HTTP infrastructure shared by MCP and CLI
• MCP Server: UniCortex.Mcp — .NET 10 + Model Context Protocol C# SDK
• CLI Tool: UniCortex.Cli — .NET 10 + ConsoleAppFramework
• UPM Package: com.veyron-sakai.uni-cortex

• Documentations~/SPEC.md — Full API endpoint and MCP tool definitions

When developing this package locally:

# Build all projects
dotnet build Tools~/UniCortex.Core/
dotnet build Tools~/UniCortex.Mcp/
dotnet build Tools~/UniCortex.Cli/

# Run tests
UNICORTEX_PROJECT_PATH=$(pwd)/Samples~ dotnet test Tools~/UniCortex.Core.Test/

# Run MCP server
dotnet run --project Tools~/UniCortex.Mcp/

# Run CLI
dotnet run --project Tools~/UniCortex.Cli/ -- editor ping

MIT License - LICENSE.txt