Unity MCP server

The Unity MCP Server is a powerful bridge that connects language models (LLMs) like Claude, OpenAI, and DeepSeek to your Unity projects, enabling AI-powered game development directly within the Unity Editor or at runtime in your compiled games.

Setting Up the MCP Server

Docker Installation (Recommended)

For the HTTP transport method:

docker run -p 8080:8080 ivanmurzakdev/unity-mcp-server

For the STDIO transport method:

docker run -t -e UNITY_MCP_CLIENT_TRANSPORT=stdio -p 8080:8080 ivanmurzakdev/unity-mcp-server

To use a custom port:

docker run -e UNITY_MCP_PORT=123 -p 123:123 ivanmurzakdev/unity-mcp-server

Binary Executable Installation

You can also run the MCP Server directly using pre-compiled binaries:

./unity-mcp-server --port 8080 --plugin-timeout 10000 --client-transport stdio

Configuration Options

The MCP Server supports various configuration options through environment variables or command-line arguments:

Option	Environment Variable	Command Line Arg	Default	Description
Port	UNITY_MCP_PORT	--port	8080	The connection port used by client, server, and plugin
Plugin Timeout	UNITY_MCP_PLUGIN_TIMEOUT	--plugin-timeout	10000	Connection timeout in ms
Client Transport	UNITY_MCP_CLIENT_TRANSPORT	--client-transport	http	Transport type: stdio or http

Connecting MCP Clients

After setting up the server, you'll need to configure your MCP client (like Claude, Cursor, or Windsurf) to connect to it. For HTTP transport, your client configuration will look like:

{
  "mcpServers": {
    "Unity-MCP": {
      "url": "http://localhost:8080"
    }
  }
}

For STDIO transport with Docker:

{
  "mcpServers": {
    "Unity-MCP": {
      "command": "docker",
      "args": [
        "run",
        "-t",
        "-e",
        "UNITY_MCP_CLIENT_TRANSPORT=stdio",
        "-p",
        "8080:8080",
        "ivanmurzakdev/unity-mcp-server"
      ]
    }
  }
}

Using MCP in Runtime Applications

To integrate MCP in your runtime applications:

// Build and start the Unity MCP Plugin
UnityMcpPlugin.BuildAndStart();

// Connect to the MCP Server with automatic retries
UnityMcpPlugin.Connect();

// When done, disconnect
UnityMcpPlugin.Disconnect();

Creating Custom MCP Tools

You can extend the MCP functionality by creating custom tools:

[McpPluginToolType]
public class Tool_GameObject
{
    [McpPluginTool
    (
        "MyCustomTask",
        Title = "Create a new GameObject"
    )]
    [Description("A tool to create custom GameObjects with specific properties")]
    public string CustomTask
    (
        [Description("Specify the properties of the GameObject")]
        string inputData
    )
    {
        // Background thread code

        return MainThread.Instance.Run(() =>
        {
            // Main thread code for Unity API operations

            return "[Success] Operation completed.";
        });
    }
}

Adding Custom MCP Prompts

Create custom prompts to guide the LLM:

[McpPluginPromptType]
public static class Prompt_ScriptingCode
{
    [McpPluginPrompt(Name = "add-event-system", Role = Role.User)]
    [Description("Implement UnityEvent-based communication system")]
    public string AddEventSystem()
    {
        return "Create event system using UnityEvents, UnityActions, or custom event delegates for decoupled communication between game systems and components.";
    }
}

The Unity MCP Server bridges the gap between AI language models and Unity, allowing developers to leverage AI for coding, asset creation, debugging, and even runtime game features like NPC behavior.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "unity-mcp" '{"command":"dotnet","args":["run","--project","path/to/unity-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "unity-mcp": {
            "command": "dotnet",
            "args": [
                "run",
                "--project",
                "path/to/unity-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "unity-mcp": {
            "command": "dotnet",
            "args": [
                "run",
                "--project",
                "path/to/unity-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect