What is Unitynaturalmcp

UnityNaturalMCP is an MCP (Model Context Protocol) server implementation for Unity designed to provide a natural user experience. It allows MCP tools developed in Unity C# to be accessed by various MCP clients like Claude Code, GitHub Copilot (VSCode), and Cursor.

Use cases

UnityNaturalMCP can be used in a variety of scenarios including asset management, console log retrieval, log clearing, and running edit mode tests within Unity. It serves as a bridge to enable efficient communication between the Unity Editor and external MCP clients.

How to use

To use UnityNaturalMCP, install the required packages and set up the project in Unity. Configure the MCP server settings, integrate with different MCP clients by adding specific configurations, and implement custom MCP tools by creating C# classes that inherit from provided SDK classes.

Key features

Key features of UnityNaturalMCP include concise communication between the Unity Editor and MCP clients, support for stdio/Streamable HTTP, a fully C# based MCP tool implementation, and compatibility with notable clients like Claude Code, GitHub Copilot, and Cursor.

Where to use

UnityNaturalMCP is particularly suitable for game development scenarios within Unity where integration with AI-assisted programming tools is beneficial. It is useful for developers looking to streamline workflows between Unity and code generation or editing tools.

UnityNaturalMCP

日本語

UnityNaturalMCP is an MCP server implementation for Unity that aims for a “natural” user experience.

MCP tools defined in Unity C# can be used directly from MCP clients such as Claude Code, GitHub Copilot(VSCode) and Cursor.

[!WARNING]
UnityNaturalMCP is still in the preview stage. It is usable in practice, but several feature additions are planned.

Features

• Concise communication flow between Unity Editor and MCP clients
• stdio/Streamable HTTP support
• Implementation of extended MCP tool entirely written in C# using MCP C# SDK
• ClaudeCode, GitHub Copilot(VSCode) and Cursor support

Requirements

• Unity 6000.0 or later
• Node.js 18.0.0 or later

Architecture

graph LR
A[MCP Client] ---|Streamable HTTP| C[UnityNaturalMCPServer]

or

graph LR
A[MCP Client] ---|stdio| B[stdio-to-streamable-http]
B ---|Streamable HTTP| C[UnityNaturalMCPServer]

UnityNaturalMCPServer

An MCP server implementation provided as a Unity Package that behaves as a Streamable HTTP server.

Clients that support Streamable HTTP, such as Github Copilot(VSCode), can communicate directly with Unity Editor through this server.

stdio-to-streamable-http

A Node.js-based stdio MCP server that relays communication between MCP clients and Unity.

Some MCP clients, such as ClaudeCode, do not support Streamable HTTP as of June 15, 2025.

By bypassing stdio input to Streamable HTTP, it enables communication between UnityNaturalMCPServer and MCP clients.

UnityNaturalMCPTest

A Unity project for functional verification and as a sample.

MCP Tools

Currently, the following MCP tools are implemented:

• RefreshAssets: Refresh Unity Editor assets
• GetCurrentConsoleLogs: Get Unity Console log history
• ClearConsoleLogs: Clear Unity Console logs
• RunEditModeTests: Run Edit Mode tests on Unity Test Runner
• RunPlayModeTests: Run Play Mode tests on Unity Test Runner

Installation

Unity

The following packages are required:

• UniTask
• NugetForUnity

Also, install the following Nuget Packages via NugetForUnity:

• System.Text.Json 9.0.x
• ModelContextProtocol 0.2.x
• Microsoft.Extensions.DependencyInjection 9.0.x

[!WARNING]
ModelContextProtocol is still in preview stage. When installing via NugetForUnity, you need to enable the Show Prerelease toggle.

You can install via UPM (Unity Package Manager):

• Edit Packages/manifest.json
• Add the following to the dependencies section:

Initial Setup

1. Open Edit > Project Settings > Unity Natural MCP in Unity Editor
2. Set the MCP server port number (default: 56780)
3. Click the Refresh button to apply the settings

[!NOTE]
56780 is just the default port. Feel free to change it to suit your project.
Note that 67 80 is the ASCII code for CP. Of course, it comes from MCP.

Claude Code

Use the following command to register an MCP server with ClaudeCode.

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

WSL2

When using MCP with Claude Code on Windows, you need to use WSL2.

To integrate WSL2 with Unity, you need to properly configure the network settings between WSL2 and the host OS.

A simple approach is to use mirror mode to connect WSL2 and the host OS.

To enable mirror mode, add the following settings to C:/Users/[username]/.wslconfig:

[wsl2]
networkingMode=mirrored

In mirror mode, you can communicate between WSL2 and the host OS via localhost.

However, when the C# server binds to localhost, it may not work as expected and connections may fail.

To work around this, set the IP Address to * in Unity’s Edit > Project Settings > Unity Natural MCP and execute Refresh.

[!CAUTION]
From a security perspective, specifying * for the IP Address is not normally recommended.
This is only meant to show a simplified setup procedure.
Please adjust accordingly based on your environment.

GitHub Copilot(VSCode)

When using GitHub Copilot(VSCode), connection via Streamable HTTP is possible.

Add the following configuration to .vscode/mcp.json:

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

Cursor

Clone this repository and add these snippets to .cursor/mcp.json.

Please replace path/to/UnityNaturalMCP with the path to the cloned UnityNaturalMCP.

{
  "mcpServers": {
    "unity-natural-mcp": {
      "command": "npm",
      "args": [
        "run",
        "start",
        "--prefix",
        "path/to/UnityNaturalMCP/stdio-to-streamable-http/"
      ],
      "env": {
        "MCP_SERVER_IP": "localhost",
        "MCP_SERVER_PORT": "56780"
      }
    }
  }
}

Custom MCP Tool Implementation

1. Create MCP Tool

In UnityNaturalMCP, you can implement MCP tools in C# using the MCP C# SDK.

Create an asmdef for the Editor and add the following script files.

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 MCP Tool Builder

To register MCP tools with the MCP server, create a class that inherits from McpBuilderScriptableObject.

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. Create ScriptableObject

1. Right-click in the project window in Unity Editor
2. Create ScriptableObject by Select Create > UnityNaturalMCP > My Custom Tool Builder
3. From Edit > Project Settings > Unity Natural MCP > Refresh, restart the MCP server to load the created tools.

Best practices for Custom MCP Tools

MCPInspector

From MCP Inspector, you can call MCP tools via Streamable HTTP and perform operational verification smoothly.

Error Handling

When errors occur within MCP tools, they are not displayed in logs.

It is recommended to use try-catch blocks to log errors and rethrow them.

[McpServerTool, Description("Example of error-returning process")]
public async void ErrorMethod()
{
  try
  {
      throw new Exception("This is an error example");
  }
  catch (Exception e)
  {
      Debug.LogError(e);
      throw;
  }
}

Asynchonous Processing

When using Unity’s API, it is necessary to consider the possibility that it may be called from threads other than the main thread.

Additionally, the return type must use ValueTask<T>.

[McpServerTool, Description("Example of asynchronous processing")]
public async ValueTask<string> AsyncMethod()
{
    await UniTask.SwitchToMainThread();
    await UniTask.Delay(1000);
    return "Finished async processing";
}

Troubleshooting

Run tests tool fails due to disconnecting

When a domain reload occurs while running tests, the connection with the Unity editor will be disconnected, and the run tests tool will fail.

Note the following:

• Run tests after the compilation is complete
• Do not run Edit Mode tests that involve domain reloading
• When running Play Mode tests, turn off Reload Domain in Edit > Project Settings > Editor > “Enter Play Mode Settings”

License

MIT License