Back to Integrations
Union ♾️ - The Unity MCP Server
A Model Context Protocol server for Unity
Last updated: 1/27/2026
README
# Union ♾️ - The Unity MCP Server
> A Model Context Protocol server for Unity
## Key Features
- 🖼️ **Multimodal Vision**: Your agent can see what you see. It can view the scene, look through any camera, watch play mode, and inspect asset thumbnails.
- 🔎 **Powerful Search**: Go beyond the project panel with simultaneous search across the hierarchy and project assets.
- ✔️ **Superior Code Analysis**: Leverage Unity's own compiler for code analysis that is more accurate than your agent's linter.
- ⏩ **Quick Start**: Get running in seconds with a single `mcp.json` configuration file.
- 🛠️ **Extensible**: Add your own project-specific tools with minimal boilerplate.
- 📅 **Always Current**: Kept up-to-date with the latest MCP protocol version — currently `2025-06-18` via the [Official MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk).
## Compatibility
| Name | Compatible | Notes |
| --------------------- | ---------- | --------------------------------------------------------------------- |
| **Models** | | |
| GPT-4.1 | ✅ | |
| Claude 4 Sonnet | ✅ | |
| Claude 4 Opus | ✅ | |
| Gemini 2.5 Pro | ✅ | |
| Gemini 2.5 Flash | ✅ | |
| o3 | ✅ | No image understanding |
| o4-mini | ✅ | |
| **Unity Versions** | | |
| Unity 6000.0.x | ✅ | Higher versions should be fine. Lower versions may work but untested. |
| **Agents** | | |
| Cursor | ✅ | |
| Rider AI | ✅ | |
| Claude Desktop | ✅ | |
| Claude Code | ✅ | Terminal requires Screen & System Audio Recording permissions on Mac |
| **Operating Systems** | | |
| Windows | ✅ | |
| Mac | ✅ | |
| Ubuntu | ❔ | Untested |
## Setup
### 1. Install [node.js](https://nodejs.org/en/download)
### 2. Configure `mcp.json`
```json
{
"mcpServers": {
"unity": {
"command": "npx",
"args": ["-y", "@nurture-tech/unity-mcp-runner", "-unityPath", "<path to unity editor>", "-projectPath", "<path to unity project>"]
}
}
}
```
This will automatically install the `is.nurture.mcp` package in your unity project. Feel free to commit those changes to source control.
## About the Tools
> Meet your Unity AI toolbox.
| Tool | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| **Assets** | |
| `get_asset_contents` | Get the full contents of an asset or sub-asset. |
| `copy_asset` | Copy an asset to a new path. |
| `import_asset` | Import an asset from the filesystem into Unity. |
| `get_asset_importer` | Get the importer settings for an asset. |
| **Prefabs** | |
| `open_prefab` | Open a Unity prefab in isolation mode so that it can be edited. |
| **Scenes** | |
| `open_scene` | Open a scene |
| `close_scene` | Close an open scene |
| `save_scene` | Save the current scene. If the scene is not dirty, this will do nothing. |
| `get_game_object` | Get the details of a game object in a loaded scene or prefab by its hierarchy path. |
| `test_active_scene` | Test the active scene by entering play mode and running for a given number of seconds. |
| **Scripting** | |
| `create_script` | Create or replace a C# code file at the given path. This also checks to make sure the script compiles. |
| `execute_code` | Execute code inside the Unity editor. |
| `get_type_info` | Get public fields and methods on a Unity fully qualified type name, including the assembly. |
| **Search** | |
| `search` | Search project assets and scene objects. |
| **Editor State** | |
| `get_state` | Get the state of the Unity Editor. |
| `get_selection` | Get the objects the user has currently selected in the editor. |
| **Vision** | |
| `focus_game_object` | Focus on a game object in the scene view. |
| `screenshot` | Retrieve a preview of what is focused in the scene view. |
## Known Issues
- The Google External Dependency Manager (EDMU) causes Unity to hang forever on startup when launched via Cursor on Windows. This is under investigation.
- The `test_active_scene` tool sometimes fails with the error message `Maximum call stack size exceeded.`
- The `search` tool occasionally fails with the error message `Search index is not ready yet. Please try again later.`
## Adding Project-Specific Tools
Union uses the official [C# MCP SDK](https://github.com/modelcontextprotocol/csharp-sdk).
1. Create a static class to hold your tools. Add the `[McpServerToolType]` annotation to the class.
2. Declare static methods to implement each tool. Add the `[McpServerTool]` annotation to each method.
3. Reference the [Services](./packages/unity/Editor/Services) directory for examples.
4. You will likely need to quit unity and restart your agent in order for it to see the new tools.
## Usage Tips
Here are some tips to get the most out of Union:
- 🚀 **Launch through your agent**: Always launch Unity through your AI agent's MCP integration. Launching Unity from the Hub will prevent the MCP server from connecting.
- 📂 **Per-project setup**: If your agent supports it, configure the MCP server in your per-project settings. This allows you to seamlessly switch between Unity projects.
- ⚙️ **Command-line arguments**: You can pass additional arguments to Unity for advanced scenarios like running in `-batchmode` or `-nographics` for CI/CD pipelines. Add a `--` separator before the Unity-specific arguments:
```json
{
"mcpServers": {
"unity": {
"command": "npx",
"args": [
"-y",
"@nurture-tech/unity-mcp-runner"
"-unityPath",
"<path to unity editor>",
"-projectPath",
".",
"--",
"-batchmode",
"-nographics"
]
}
}
}
```
- ⚠️ **Important**: Do not use the `-logFile` command-line argument. The MCP server relies on Unity's standard output for communication.
- 🖥️ **Split screen for vision**: For tools like `screenshot`, ensure the Unity editor is visible on your screen otherwise it will end up screenshotting the foreground window.
Installation
Add this MCP to your configuration:
{
"mcpServers": {
"union-the-unity-mcp-server": {
// See GitHub repository for configuration
}
}
}See the GitHub repository for full installation instructions.