DOCSEARCHbyAlgolia
Submit Docs

UnityNaturalMCP

repository·main·Indexed 41 days ago

https://github.com/notargs/unitynaturalmcp

An MCP (Model Context Protocol) server implementation for Unity version 0.6.0. It enables AI coding agents such as Claude Code, GitHub Copilot, and Cursor to interact directly with the Unity Editor to refresh assets, read console logs, and run tests. The package supports custom MCP tool implementation in C# and integrates with various clients via Streamable HTTP or stdio relays.

Tokens
1.5K
Snippets
6
Records
8
Agent score
1%

What's inside UnityNaturalMCP

  1. Configure UnityNaturalMCP Server Settings

    main

    After installation, perform the initial setup in the Unity Editor:

    1. Navigate to Edit > Project Settings > Unity Natural MCP.
    2. Set the MCP server port number (the default is 56780).
    3. Click the Refresh button to apply the settings and start/restart the server.

    Note on IP Address: If you are using WSL2 with mirror mode, you may need to set the IP Address to * in these settings to ensure connectivity between the host and the WSL2 environment.

  2. Configure Claude Code

    main

    To register the UnityNaturalMCP server with Claude Code, use the following command in your terminal. Ensure the port matches your Unity project settings (default 56780).

    claude mcp add -s project --transport http unity-natural-mcp http://localhost:56780/mcp

  3. Install UnityNaturalMCP in Unity

    main

    To install UnityNaturalMCP, you must first ensure the following dependencies are present in your project:

    Required UPM Packages:

    Required NuGet Packages (via NugetForUnity):

    • System.Text.Json 9.0.x
    • ModelContextProtocol 0.2.x (Note: You must enable the Show Prerelease toggle in NugetForUnity to find this)
    • Microsoft.Extensions.DependencyInjection 9.0.x

    Installation via UPM: Add the following dependency to your Packages/manifest.json:

    "jp.notargs.unity-natural-mcp": "https://github.com/notargs/UnityNaturalMCP.git?path=/UnityNaturalMCPServer"

  4. Configure GitHub Copilot (VSCode)

    main

    GitHub Copilot supports direct communication via Streamable HTTP. Add the following configuration to your .vscode/mcp.json file:

    {
  "servers": {
    "unity-natural-mcp": {
      "url": "http://localhost:56780/mcp"
    }
  }
}

  5. Configure Gemini CLI

    main

    Gemini CLI supports Streamable HTTP. Create a .gemini/settings.json file at your project root and add the following (adjust the port if you changed it from the default 56780):

    {
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:56780/mcp"
    }
  }
}

  6. Implement Custom MCP Tools in C#

    main

    You can extend UnityNaturalMCP by defining your own tools using the MCP C# SDK. This requires three steps:

    1. Define the Tool Class

    Create an Editor assembly definition (asmdef) and implement your tool class using the [McpServerToolType] and [McpServerTool] attributes.

    using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType, Description("Description of custom MCP tool")]
public class MyCustomMCPTool
{
    [McpServerTool, Description("Method description")]
    public string MyMethod()
    {
        return "Hello from Unity!";
    }
}

    2. Create a Tool Builder

    Create a class inheriting from McpBuilderScriptableObject to register your tool class with the server.

    using Microsoft.Extensions.DependencyInjection;
using UnityEngine;
using UnityNaturalMCP.Editor;

[CreateAssetMenu(fileName = "MyCustomMCPToolBuilder", 
                 menuName = "UnityNaturalMCP/My Custom Tool Builder")]
public class MyCustomMCPToolBuilder : McpBuilderScriptableObject
{
    public override void Build(IMcpServerBuilder builder)
    {
        builder.WithTools<MyCustomMCPTool>();
    }
}

    3. Register the Tool in Unity

    1. In the Unity Project window, right-click and select Create > UnityNaturalMCP > My Custom Tool Builder.
    2. Go to Edit > Project Settings > Unity Natural MCP and click Refresh to restart the server and load the new tools.

    Best Practices

    • Error Handling: Wrap tool logic in try-catch blocks and use Debug.LogError to ensure errors are visible in Unity logs, as MCP clients may not automatically surface internal exceptions.
    • Asynchronous Processing: If using Unity APIs, ensure you switch to the main thread using UniTask.SwitchToMainThread() and use ValueTask<T> as the return type.
    [McpServerTool, Description("Example of asynchronous processing")]
public async ValueTask<string> AsyncMethod()
{
    await UniTask.SwitchToMainThread();
    await UniTask.Delay(1000);
    return "Finished async processing";
}

  7. Configure Cursor via stdio relay

    main

    As of June 23, 2025, Cursor does not support Streamable HTTP. You must use the mcp-stdio-to-streamable-http relay.

    1. Download the latest release of mcp-stdio-to-streamable-http.
    2. Clone/extract the repository.
    3. Add the following configuration to .cursor/mcp.json, replacing path/to/mcp-stdio-to-streamable-http with your actual local path:
    {
  "mcpServers": {
    "unity-natural-mcp": {
      "command": "node",
      "args": ["path/to/mcp-stdio-to-streamable-http/dist/index.js"],
      "env": {
        "MCP_SERVER_IP": "localhost",
        "MCP_SERVER_PORT": "56780"
      }
    }
  }
}

  8. Troubleshoot Run Tests tool failures

    main

    If the RunEditModeTests or RunPlayModeTests tools fail due to disconnection, it is likely caused by a domain reload during the test execution.

    Solutions:

    • Ensure compilation is fully complete before running tests.
    • Avoid running Edit Mode tests that trigger domain reloading.
    • For Play Mode tests, disable domain reloading in Edit > Project Settings > Editor > Enter Play Mode Settings (uncheck Reload Domain).