unity-mcp/Server

MCP for Unity Server

Model Context Protocol server for Unity Editor integration. Control Unity through natural language using AI assistants like Claude, Cursor, and more.

Maintained by Coplay - This project is not affiliated with Unity Technologies.

💬 Join our community: Discord Server

Required: Install the Unity MCP Plugin to connect Unity Editor with this MCP server. You also need uvx (requires uv) to run the server.

---

Installation

Option 1: PyPI

Install and run directly from PyPI using uvx.

Run Server (HTTP):

uvx --from mcpforunityserver mcp-for-unity --transport http --http-url http://localhost:8080

MCP Client Configuration (HTTP):

{
  "mcpServers": {
    "UnityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

MCP Client Configuration (stdio):

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uvx",
      "args": [
        "--from",
        "mcpforunityserver",
        "mcp-for-unity",
        "--transport",
        "stdio"
      ]
    }
  }
}

Option 2: From GitHub Source

Use this to run the latest released version from the repository. Change the version to main to run the latest unreleased changes from the repository.

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/CoplayDev/unity-mcp@v9.3.1#subdirectory=Server",
        "mcp-for-unity",
        "--transport",
        "stdio"
      ]
    }
  }
}

Option 3: Docker

Use Pre-built Image:

docker run -p 8080:8080 msanatan/mcp-for-unity-server:latest --transport http --http-url http://0.0.0.0:8080

Build Locally:

docker build -t unity-mcp-server .
docker run -p 8080:8080 unity-mcp-server --transport http --http-url http://0.0.0.0:8080

Configure your MCP client with "url": "http://localhost:8080/mcp".

Option 4: Local Development

For contributing or modifying the server code:

# Clone the repository
git clone https://github.com/CoplayDev/unity-mcp.git
cd unity-mcp/Server

# Run with uv
uv run src/main.py --transport stdio

---

Configuration

The server connects to Unity Editor automatically when both are running. Most users do not need to change any settings.

CLI options

These options apply to the mcp-for-unity command (whether run via uvx, Docker, or python src/main.py).

• --transport {stdio,http} - Transport protocol (default: stdio)
• --http-url URL - Base URL used to derive host/port defaults (default: http://localhost:8080)
• --http-host HOST - Override HTTP bind host (overrides URL host)
• --http-port PORT - Override HTTP bind port (overrides URL port)
• --http-remote-hosted - Treat HTTP transport as remotely hosted
  • Requires API key authentication (see below)
  • Disables local/CLI-only HTTP routes (/api/command, /api/instances, /api/custom-tools)
  • Forces explicit Unity instance selection for MCP tool/resource calls
  • Isolates Unity sessions per user
• --api-key-validation-url URL - External endpoint to validate API keys (required when --http-remote-hosted is set)
• --api-key-login-url URL - URL where users can obtain/manage API keys (served by /api/auth/login-url)
• --api-key-cache-ttl SECONDS - Cache duration for validated keys (default: 300)
• --api-key-service-token-header HEADER - Header name for server-to-auth-service authentication (e.g. X-Service-Token)
• --api-key-service-token TOKEN - Token value sent to the auth service for server authentication
• --default-instance INSTANCE - Default Unity instance to target (project name, hash, or Name@hash)
• --project-scoped-tools - Keep custom tools scoped to the active Unity project and enable the custom tools resource
• --unity-instance-token TOKEN - Optional per-launch token set by Unity for deterministic lifecycle management
• --pidfile PATH - Optional path where the server writes its PID on startup (used by Unity-managed terminal launches)

Environment variables

• UNITY_MCP_TRANSPORT - Transport protocol: stdio or http
• UNITY_MCP_HTTP_URL - HTTP server URL (default: http://localhost:8080)
• UNITY_MCP_HTTP_HOST - HTTP bind host (overrides URL host)
• UNITY_MCP_HTTP_PORT - HTTP bind port (overrides URL port)
• UNITY_MCP_HTTP_REMOTE_HOSTED - Enable remote-hosted mode (true, 1, or yes)
• UNITY_MCP_DEFAULT_INSTANCE - Default Unity instance to target (project name, hash, or Name@hash)
• UNITY_MCP_SKIP_STARTUP_CONNECT=1 - Skip initial Unity connection attempt on startup

API key authentication (remote-hosted mode):

• UNITY_MCP_API_KEY_VALIDATION_URL - External endpoint to validate API keys
• UNITY_MCP_API_KEY_LOGIN_URL - URL where users can obtain/manage API keys
• UNITY_MCP_API_KEY_CACHE_TTL - Cache TTL for validated keys in seconds (default: 300)
• UNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER - Header name for server-to-auth-service authentication
• UNITY_MCP_API_KEY_SERVICE_TOKEN - Token value sent to the auth service for server authentication

Telemetry:

• DISABLE_TELEMETRY=1 - Disable anonymous telemetry (opt-out)
• UNITY_MCP_DISABLE_TELEMETRY=1 - Same as DISABLE_TELEMETRY
• MCP_DISABLE_TELEMETRY=1 - Same as DISABLE_TELEMETRY
• UNITY_MCP_TELEMETRY_ENDPOINT - Override telemetry endpoint URL
• UNITY_MCP_TELEMETRY_TIMEOUT - Override telemetry request timeout (seconds)

Examples

Stdio (default):

uvx --from mcpforunityserver mcp-for-unity --transport stdio

HTTP (local):

uvx --from mcpforunityserver mcp-for-unity --transport http --http-host 127.0.0.1 --http-port 8080

HTTP (remote-hosted with API key auth):

uvx --from mcpforunityserver mcp-for-unity \
  --transport http \
  --http-host 0.0.0.0 \
  --http-port 8080 \
  --http-remote-hosted \
  --api-key-validation-url https://auth.example.com/api/validate-key \
  --api-key-login-url https://app.example.com/api-keys

Disable telemetry:

DISABLE_TELEMETRY=1 uvx --from mcpforunityserver mcp-for-unity --transport stdio

---

Remote-Hosted Mode

When deploying the server as a shared remote service (e.g. for a team or Asset Store users), enable --http-remote-hosted to activate API key authentication and per-user session isolation.

Requirements:

• An external HTTP endpoint that validates API keys. The server POSTs {"api_key": "..."} and expects {"valid": true, "user_id": "..."} or {"valid": false} in response.
• --api-key-validation-url must be provided (or UNITY_MCP_API_KEY_VALIDATION_URL). The server exits with code 1 if this is missing.

What changes in remote-hosted mode:

• All MCP tool/resource calls and Unity plugin WebSocket connections require a valid X-API-Key header.
• Each user only sees Unity instances that connected with their API key (session isolation).
• Auto-selection of a sole Unity instance is disabled; users must explicitly call set_active_instance.
• CLI REST routes (/api/command, /api/instances, /api/custom-tools) are disabled.
• /health and /api/auth/login-url remain accessible without authentication.

MCP client config with API key:

{
  "mcpServers": {
    "UnityMCP": {
      "url": "http://remote-server:8080/mcp",
      "headers": {
        "X-API-Key": "<your-api-key>"
      }
    }
  }
}

For full details, see Remote Server Auth Guide and Architecture Reference.

---

MCP Resources

The server provides read-only MCP resources for querying Unity Editor state. Resources provide up-to-date information about your Unity project without modifying it.

Accessing Resources:

Resources are accessed by their URI (not their name). Always use ListMcpResources to get the correct URI format.

Example URIs:

• mcpforunity://editor/state - Editor readiness snapshot
• mcpforunity://project/tags - All project tags
• mcpforunity://scene/gameobject/{instance_id} - GameObject details by ID
• mcpforunity://prefab/{encoded_path} - Prefab info by asset path

Important: Resource names use underscores (e.g., editor_state) but URIs use slashes/hyphens (e.g., mcpforunity://editor/state). Always use the URI from ListMcpResources() when reading resources.

All resource descriptions now include their URI for easy reference. List available resources to see the complete catalog with URIs.

---

Example Prompts

Once connected, try these commands in your AI assistant:

• "Create a 3D player controller with WASD movement"
• "Add a rotating cube to the scene with a red material"
• "Create a simple platformer level with obstacles"
• "Generate a shader that creates a holographic effect"
• "List all GameObjects in the current scene"

---

Documentation

For complete documentation, troubleshooting, and advanced usage:

📖 Full Documentation

---

Requirements

• Python: 3.10 or newer
• Unity Editor: 2021.3 LTS or newer
• uv: Python package manager (Installation Guide)

---

License

MIT License - See LICENSE