UnityNaturalMCP

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

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.

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

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

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

An MCP server implementation provided as a Unity Package that behaves as aStreamable HTTPserver.

Clients that supportStreamable HTTP, such asGithub Copilot(VSCode), can communicate directly with Unity Editor through this server.

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

Some MCP clients, such asCursor, do not supportStreamable HTTPas of June 23, 2025.

By bypassing stdio input toStreamable HTTP, it enables communication betweenUnityNaturalMCPServerand MCP clients.

A Unity project for functional verification and as a sample.

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

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 theShow Prereleasetoggle.

You can install via UPM (Unity Package Manager):

- EditPackages/manifest.json
- Add the following to thedependenciessection:

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

- OpenEdit > Project Settings > Unity Natural MCPin Unity Editor
- Set the MCP server port number (default: 56780)
- Click theRefreshbutton to apply the settings

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

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

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 toC:/Users/[username]/.wslconfig:

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 toin Unity'sEdit > Project Settings > Unity Natural MCPand executeRefresh.

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

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 does not supportStreamable HTTPas of June 23, 2025. You need to connect viastdio. Please download the latest mcp-stdio-to-streamable-http frommcp-stdio-to-streamable-http Releases.

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

Streamable HTTP is supported. Create.gemini/settings.jsonat the root and add the following (if you use a custom port, replace56780):

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

For more details, see the Gemini CLI documentation:Gemini CLI documentation: HTTP-based MCP server

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

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

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

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>(); } }

- Right-click in the project window in Unity Editor
- Create ScriptableObject by SelectCreate > UnityNaturalMCP > My Custom Tool Builder
- FromEdit > Project Settings > Unity Natural MCP > Refresh, restart the MCP server to load the created tools.

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

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

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 useValueTask<T>.

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

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.

- 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 inEdit > Project Settings > Editor > "Enter Play Mode Settings"

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

An MCP server for Unity, enabling AI assistants to interact with projects in real-time, access scene data, and execute code.

Manipulate Adventure Game Studio (AGS) compiled room (.crm) files to enable AI-powered game development.

Godot Engine integration: 17 tools for game development

An MCP server for AI coding assistants to control, inspect, and modify Bevy applications using the Bevy Remote Protocol (BRP).

Control, inspect, and mutate Bevy applications with AI coding assistants via the Bevy Remote Protocol (BRP).

A server for Ebitengine games that provides debugging and recording tools by capturing game state.

Fennara MCP connects AI agents like Codex, Cursor, Claude Code, and Claude Desktop to Godot-aware tools for real Godot projects. It focuses on feedback from Godot: GDScript diagnostics, scene validation, runtime errors, scene inspection, node properties, screenshots, SemanticSearch, and patch-and-rerun workflows.

an open-source MCP server that unifies Roblox Studio, Unity, Unreal Engine, and Blender into a single AI control plane for game development workflows.

7 tools for 3D game development — character viewers, level editors, physics games, particle effects, 3D inventories with SceneView. 156 tests.

The intelligent MCP server for AI-assisted Godot 4 development. 35 tools for spatial intelligence, code understanding, flow tracing, and visual debugging. 22 free, full suite $19.