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.2.0#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. No additional configuration needed.

Environment Variables:

• DISABLE_TELEMETRY=true - Opt out of anonymous usage analytics
• LOG_LEVEL=DEBUG - Enable detailed logging (default: INFO)

---

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