Skip to content
Back to search

UnityNaturalMCP

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/notargs--unitynaturalmcp/badge.svg)](/listings/notargs--unitynaturalmcp)

HTML

<a href="/listings/notargs--unitynaturalmcp"><img src="/api/listings/notargs--unitynaturalmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Unity

The following packages are required: - [UniTask](https://github.com/Cysharp/UniTask) - [NugetForUnity](https://github.com/GlitchEnzo/NuGetForUnity)

Also, install the following Nuget Packages via NugetForUnity: - [System.Text.Json 9.0.x](https://www.nuget.org/packages/System.Text.Json/) - [ModelContextProtocol 0.2.x](https://www.nuget.org/packages/ModelContextProtocol/) - [Microsoft.Extensions.DependencyInjection 9.0.x](https://www.nuget.org/packages/Microsoft.Extensions.DependencyInjection/)

> [!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:

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

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

Cursor does not support `Streamable HTTP` as of June 23, 2025. You need to connect via `stdio`. Please download the latest mcp-stdio-to-streamable-http from [mcp-stdio-to-streamable-http Releases](https://github.com/notargs/mcp-stdio-to-streamable-http/releases).

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

Please replace `path/to/mcp-stdio-to-streamable-http` with the path to the cloned `mcp-stdio-to-streamable-http`.

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

Gemini CLI

Streamable HTTP is supported. Create `.gemini/settings.json` at the root and add the following (if you use a custom port, replace `56780`):

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

For more details, see the Gemini CLI documentation: [Gemini CLI documentation: HTTP-based MCP server](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#http-based-mcp-server)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # UnityNaturalMCP
  2. ![Stars](https://img.shields.io/github/stars/notargs/UnityNaturalMCP)
  3. ![Forks](https://img.shields.io/github/forks/notargs/UnityNaturalMCP)
  4. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/notargs/UnityNaturalMCP)
  5. ![Unity](https://img.shields.io/badge/Unity-6000.0-111?logo=unity)
  6. ![.NET C# 9.0](https://img.shields.io/badge/.NET-C%23_9.0-512BD4.svg)
  7. ![GitHubCopilot](https://img.shields.io/badge/GitHub_Copilot-111?logo=githubcopilot)
  8. ![ClaudeCode](https://img.shields.io/badge/Claude_Code-555?logo=claude)
  9. ![Cursor](https://img.shields.io/badge/Cursor-111)
  10. ![WSL2](https://img.shields.io/badge/WSL2-28b)
  11. [日本語](README.ja.md)
  12. UnityNaturalMCP is an MCP server implementation for Unity that aims for a "natural" user experience.
  13. MCP tools defined in Unity C# can be used directly from MCP clients such as Claude Code, GitHub Copilot(VSCode) and Cursor.
  14. > [!WARNING]
  15. > UnityNaturalMCP is still in the preview stage. It is usable in practice, but several feature additions are planned.
  16. ## Features
  17. - Concise communication flow between Unity Editor and MCP clients
  18. - stdio/Streamable HTTP support
  19. - Implementation of extended MCP tool entirely written in C# using [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
  20. - ClaudeCode, GitHub Copilot(VSCode) and Cursor support
  21. ## Requirements
  22. - Unity 6000.0 or later
  23. - Node.js 18.0.0 or later (if using `mcp-stdio-to-streamable-http`)
  24. ## Architecture
  25. ```mermaid
  26. graph LR
  27. A[MCP Client] ---|Streamable HTTP| C[UnityNaturalMCPServer]
  28. ```
  29. or
  30. ```mermaid
  31. graph LR
  32. A[MCP Client] ---|stdio| B[stdio-to-streamable-http]
  33. B ---|Streamable HTTP| C[UnityNaturalMCPServer]
  34. ```
  35. ### UnityNaturalMCPServer
  36. An MCP server implementation provided as a Unity Package that behaves as a `Streamable HTTP` server.
  37. Clients that support `Streamable HTTP`, such as `Github Copilot(VSCode)`, can communicate directly with Unity Editor through this server.
  38. ### mcp-stdio-to-streamable-http
  39. [mcp-stdio-to-streamable-http](https://github.com/notargs/mcp-stdio-to-streamable-http)
  40. A Node.js-based stdio MCP server that relays communication between MCP clients and Unity.
  41. Some MCP clients, such as `Cursor`, do not support `Streamable HTTP` as of June 23, 2025.
  42. By bypassing stdio input to `Streamable HTTP`, it enables communication between `UnityNaturalMCPServer` and MCP clients.
  43. ### UnityNaturalMCPTest
  44. A Unity project for functional verification and as a sample.
  45. ## MCP Tools
  46. Currently, the following MCP tools are implemented:
  47. - **RefreshAssets**: Refresh Unity Editor assets
  48. - **GetCurrentConsoleLogs**: Get Unity Console log history
  49. - **ClearConsoleLogs**: Clear Unity Console logs
  50. - **RunEditModeTests**: Run Edit Mode tests on Unity Test Runner
  51. - **RunPlayModeTests**: Run Play Mode tests on Unity Test Runner
  52. ## Installation
  53. ### Unity
  54. The following packages are required:
  55. - [UniTask](https://github.com/Cysharp/UniTask)
  56. - [NugetForUnity](https://github.com/GlitchEnzo/NuGetForUnity)
  57. Also, install the following Nuget Packages via NugetForUnity:
  58. - [System.Text.Json 9.0.x](https://www.nuget.org/packages/System.Text.Json/)
  59. - [ModelContextProtocol 0.2.x](https://www.nuget.org/packages/ModelContextProtocol/)
  60. - [Microsoft.Extensions.DependencyInjection 9.0.x](https://www.nuget.org/packages/Microsoft.Extensions.DependencyInjection/)
  61. > [!WARNING]
  62. > ModelContextProtocol is still in preview stage. When installing via NugetForUnity, you need to enable the `Show Prerelease` toggle.
  63. You can install via UPM (Unity Package Manager):
  64. - Edit `Packages/manifest.json`
  65. - Add the following to the `dependencies` section:
  66. ```json
  67. "jp.notargs.unity-natural-mcp": "https://github.com/notargs/UnityNaturalMCP.git?path=/UnityNaturalMCPServer"
  68. ```
  69. #### Initial Setup
  70. 1. Open `Edit > Project Settings > Unity Natural MCP` in Unity Editor
  71. 2. Set the MCP server port number (default: 56780)
  72. 3. Click the `Refresh` button to apply the settings
  73. > [!NOTE]
  74. > `56780` is just the default port. Feel free to change it to suit your project.
  75. > Note that `67 80` is the ASCII code for `CP`. Of course, it comes from MCP.
  76. ![Setting](docs/images/settings.png)
  77. ### Claude Code
  78. Use the following command to register an MCP server with ClaudeCode.
  79. ```shell
  80. claude mcp add -s project --transport http unity-natural-mcp http://localhost:56780/mcp
  81. ```
  82. ### WSL2
  83. When using MCP with Claude Code on Windows, you need to use WSL2.
  84. To integrate WSL2 with Unity, you need to properly configure the network settings between WSL2 and the host OS.
  85. A simple approach is to use mirror mode to connect WSL2 and the host OS.
  86. To enable mirror mode, add the following settings to `C:/Users/[username]/.wslconfig`:
  87. ```ini
  88. [wsl2]
  89. networkingMode=mirrored
  90. ```
  91. In mirror mode, you can communicate between WSL2 and the host OS via localhost.
  92. However, when the C# server binds to localhost, it may not work as expected and connections may fail.
  93. To work around this, set the IP Address to `*` in Unity's `Edit > Project Settings > Unity Natural MCP` and execute `Refresh`.
  94. > [!CAUTION]
  95. > From a security perspective, specifying `*` for the IP Address is not normally recommended.
  96. > This is only meant to show a simplified setup procedure.
  97. > Please adjust accordingly based on your environment.
  98. ### GitHub Copilot(VSCode)
  99. When using GitHub Copilot(VSCode), connection via Streamable HTTP is possible.
  100. Add the following configuration to `.vscode/mcp.json`:
  101. ```json
  102. {
  103. "servers": {
  104. "unity-natural-mcp": {
  105. "url": "http://localhost:56780/mcp"
  106. }
  107. }
  108. }
  109. ```
  110. ### Cursor
  111. Cursor does not support `Streamable HTTP` as of June 23, 2025.
  112. You need to connect via `stdio`.
  113. Please download the latest mcp-stdio-to-streamable-http from [mcp-stdio-to-streamable-http Releases](https://github.com/notargs/mcp-stdio-to-streamable-http/releases).
  114. Clone this repository and add these snippets to `.cursor/mcp.json`.
  115. Please replace `path/to/mcp-stdio-to-streamable-http` with the path to the cloned `mcp-stdio-to-streamable-http`.
  116. ```json
  117. {
  118. "mcpServers": {
  119. "unity-natural-mcp": {
  120. "command": "node",
  121. "args": ["path/to/mcp-stdio-to-streamable-http/dist/index.js"],
  122. "env": {
  123. "MCP_SERVER_IP": "localhost",
  124. "MCP_SERVER_PORT": "56780"
  125. }
  126. }}
  127. }
  128. ```
  129. ### Gemini CLI
  130. Streamable HTTP is supported. Create `.gemini/settings.json` at the root and add the following (if you use a custom port, replace `56780`):
  131. ```json
  132. {
  133. "mcpServers": {
  134. "httpServer": {
  135. "httpUrl": "http://localhost:56780/mcp"
  136. }
  137. }
  138. }
  139. ```
  140. For more details, see the Gemini CLI documentation:
  141. [Gemini CLI documentation: HTTP-based MCP server](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#http-based-mcp-server)
  142. ## Custom MCP Tool Implementation
  143. ### 1. Create MCP Tool
  144. In UnityNaturalMCP, you can implement MCP tools in C# using the [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk).
  145. Create an asmdef for the Editor and add the following script files.
  146. ```csharp
  147. using System.ComponentModel;
  148. using ModelContextProtocol.Server;
  149. [McpServerToolType, Description("Description of custom MCP tool")]
  150. public class MyCustomMCPTool
  151. {
  152. [McpServerTool, Description("Method description")]
  153. public string MyMethod()
  154. {
  155. return "Hello from Unity!";
  156. }
  157. }
  158. ```
  159. ### 2. Create MCP Tool Builder
  160. To register MCP tools with the MCP server, create a class that inherits from `McpBuilderScriptableObject`.
  161. ```csharp
  162. using Microsoft.Extensions.DependencyInjection;
  163. using UnityEngine;
  164. using UnityNaturalMCP.Editor;
  165. [CreateAssetMenu(fileName = "MyCustomMCPToolBuilder",
  166. menuName = "UnityNaturalMCP/My Custom Tool Builder")]
  167. public class MyCustomMCPToolBuilder : McpBuilderScriptableObject
  168. {
  169. public override void Build(IMcpServerBuilder builder)
  170. {
  171. builder.WithTools<MyCustomMCPTool>();
  172. }
  173. }
  174. ```
  175. ### 3. Create ScriptableObject
  176. 1. Right-click in the project window in Unity Editor
  177. 2. Create ScriptableObject by Select `Create > UnityNaturalMCP > My Custom Tool Builder`
  178. 3. From `Edit > Project Settings > Unity Natural MCP > Refresh`, restart the MCP server to load the created tools.
  179. ### Best practices for Custom MCP Tools
  180. #### MCPInspector
  181. From [MCP Inspector](https://github.com/modelcontextprotocol/inspector), you can call MCP tools via Streamable HTTP and perform operational verification smoothly.
  182. ![MCPInspector](docs/images/mcp_inspector.png)
  183. #### Error Handling
  184. When errors occur within MCP tools, they are not displayed in logs.
  185. It is recommended to use try-catch blocks to log errors and rethrow them.
  186. ```csharp
  187. [McpServerTool, Description("Example of error-returning process")]
  188. public async void ErrorMethod()
  189. {
  190. try
  191. {
  192. throw new Exception("This is an error example");
  193. }
  194. catch (Exception e)
  195. {
  196. Debug.LogError(e);
  197. throw;
  198. }
  199. }
  200. ```
  201. #### Asynchonous Processing
  202. When using Unity's API, it is necessary to consider the possibility that it may be called from threads other than the main thread.
  203. Additionally, the return type must use `ValueTask<T>`.
  204. ```csharp
  205. [McpServerTool, Description("Example of asynchronous processing")]
  206. public async ValueTask<string> AsyncMethod()
  207. {
  208. await UniTask.SwitchToMainThread();
  209. await UniTask.Delay(1000);
  210. return "Finished async processing";
  211. }
  212. ```
  213. ## Troubleshooting
  214. ### Run tests tool fails due to disconnecting
  215. When a domain reload occurs while running tests, the connection with the Unity editor will be disconnected, and the run tests tool will fail.
  216. Note the following:
  217. - Run tests after the compilation is complete
  218. - Do not run Edit Mode tests that involve domain reloading
  219. - When running Play Mode tests, turn off Reload Domain in **Edit > Project Settings > Editor > "Enter Play Mode Settings"**
  220. ## License
  221. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.