Unity MCP Server

How to use

To use the MCP server, start Unity and run the MCP integration to expose a server endpoint. The server provides an HTTP endpoint at localhost and can also be driven from a local process through standard input/output (stdio) integration. You can connect compatible MCP clients (such as Claude Desktop, Cursor, Windsurf, or VS Code with MCP support) to the server and begin giving natural language prompts to manipulate Unity content.

How to install

Prerequisites you need before installation:

• Unity 2021.3 LTS+ (install via Unity Hub)

• Python 3.10+
• uvx (or uv)

• Claude Desktop
• Claude Code
• Cursor
• VS Code Copilot
• GitHub Copilot CLI
• Windsurf
• other MCP clients

Step-by-step setup inside Unity and your environment:

HTTP server and stdio runtime configurations

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

{
  "mcpServers": {
    "unityMCP": {
      "command": "uvx",
      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
    }
  }
}

For Windows, run the same stdio configuration with the Windows path for uvx if you use the same approach. The final command and arguments should be used exactly as shown here.

Additional configuration tips

If auto-setup does not configure correctly, place the following in your MCP client configuration to point to the local HTTP server or stdio runner. You can also adapt this for your code editor integration.

Multiple Unity instances

MCP for Unity can target multiple Unity Editors. To select a specific instance, ask your AI to check the unity_instances resource, then use set_active_instance with a value like Name@hash (for example, MyProject@abc123). All subsequent tools will apply to that instance.

Roslyn Script Validation (Advanced)

For strict Roslyn-based validation of scripts, follow the steps below to enable runtime code execution validation inside Unity. This enables advanced checks for undefined namespaces, types, and methods.

Troubleshooting

If you run into issues, check common points of failure such as the bridge connection, server startup, or client connectivity. Review the MCP status in Unity and confirm that the HTTP server is running at the expected URL. If problems persist, consult the Discord community or raise an issue with clear reproduction steps.

Security and privacy

The server defaults to secure behavior with optional opt-ins for broader network access. Telemetry is anonymized and privacy-preserving by default, with an option to disable telemetry via an environment flag.

Contributing

Contribute by forking the project, creating a feature branch, and submitting a pull request after implementing your changes in a local MCP-enabled workflow.

Telemetry & Privacy

Anonymous telemetry is collected to improve the MCP experience. You can opt out by setting the DISABLE_TELEMETRY environment variable to true.

Security

Network defaults aim to be secure by default. Local HTTP endpoints bind to loopback by default. Enabling LAN binding or remote access requires explicit opt-ins in the Advanced Settings.

License and support

MIT license. For help, reach out via the community channels provided in the project materials.

Notes on tools and capabilities

The MCP server offers a set of actions to control Unity elements such as assets, scenes, materials, scripts, and editor functions. These tools enable automated workflows and assistance from compatible MCP clients.

apply_text_edits

Apply text edits to Unity scripts or assets based on prompts.

batch_execute

Execute multiple MCP actions in a batch for speed and efficiency.

create_script

Generate a new Unity C# script from a prompt.

debug_request_context

Inspect the current request context for debugging prompts.

delete_script

Remove a Unity script from the project.

execute_custom_tool

Run a custom tool integrated into the MCP workflow.

execute_menu_item

Trigger a Unity editor menu item via an MCP command.

find_gameobjects

Search for GameObjects in the current scene by criteria.

find_in_file

Search within a file for text patterns and report matches.

get_sha

Retrieve a SHA hash for a given artifact or script.

get_test_job

Fetch details about a test job in the MCP workflow.

manage_animation

Modify or create animation assets and controllers.

manage_asset

Handle Unity assets such as textures, models, audio.

manage_components

Add, remove, or modify components on GameObjects.

manage_editor

Interact with editor settings and tooling.

manage_gameobject

Create, rename, or delete GameObjects; adjust transforms.

manage_material

Manage materials, shaders, and properties.

manage_prefabs

Create or update prefabs and their instances.

manage_scene

Load, save, or modify Unity scenes.

manage_script

Manage scripts, update code, and apply changes.

manage_script_capabilities

Configure capabilities available to scripts.

manage_scriptable_object

Handle ScriptableObject assets and their data.

manage_shader

Edit or assign shaders to materials.

manage_texture

Edit texture properties and import settings.

manage_ui

Modify UI elements and layouts.

manage_vfx

Control visual effects assets and systems.

read_console

Read Unity console output for prompts or debugging.

refresh_unity

Refresh or restart the Unity session from MCP.

run_tests

Execute test suites within the Unity project.

script_apply_edits

Apply code edits automatically to scripts.

set_active_instance

Switch the active Unity Editor instance for subsequent actions.

validate_script

Validate scripts for syntax and semantic correctness.