Labsco
notargs logo

UnityNaturalMCP

โ˜… 163

from notargs

An MCP server implementation for the Unity game engine that enables a natural user experience.

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedFreeQuick setup
#git#security

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

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.

mcp-stdio-to-streamable-http

mcp-stdio-to-streamable-http

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

Some MCP clients, such as Cursor, do not support Streamable HTTP as of June 23, 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

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.

MCPInspector

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";
}