Provides comprehensive control over the Unity Editor, enabling programmatic manipulation of assets, scene management, material editing, script creation/editing, and automation of editor functions like undo, play, and build.
MCP for Unity ✨
Proudly sponsored and maintained by Coplay, the AI assistant for Unity. Read the backstory here.
Create your Unity apps with LLMs!
MCP for Unity acts as a bridge, allowing AI assistants (like Claude, Cursor) to interact directly with your Unity Editor via a local MCP (Model Context Protocol) Client. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.
💬 Join Our Community
Discord
Get help, share ideas, and collaborate with other MCP for Unity developers!
Key Features 🚀
- 🗣️ Natural Language Control: Instruct your LLM to perform Unity tasks.
- 🛠️ Powerful Tools: Manage assets, scenes, materials, scripts, and editor functions.
- 🤖 Automation: Automate repetitive Unity workflows.
- 🧩 Extensible: Designed to work with various MCP Clients.
Your LLM can use functions like:
read_console
: Gets messages from or clears the console.manage_script
: Manages C# scripts (create, read, update, delete).manage_editor
: Controls and queries the editor's state and settings.manage_scene
: Manages scenes (load, save, create, get hierarchy, etc.).manage_asset
: Performs asset operations (import, create, modify, delete, etc.).manage_shader
: Performs shader CRUD operations (create, read, modify, delete).manage_gameobject
: Manages GameObjects: create, modify, delete, find, and component operations.execute_menu_item
: Executes a menu item via its path (e.g., "File/Save Project").
How It Works 🤔
MCP for Unity connects your tools using two components:
- MCP for Unity Bridge: A Unity package running inside the Editor. (Installed via Package Manager).
- MCP for Unity Server: A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed automatically by the package on first run or via Auto-Setup; manual setup is available as a fallback).
Flow: [Your LLM via MCP Client] <-> [MCP for Unity Server (Python)] <-> [MCP for Unity Bridge (Unity Editor)]
Installation ⚙️
Note: The setup is constantly improving as we update the package. Check back if you randomly start to run into issues.
Prerequisites
- Python: Version 3.12 or newer. Download Python
- Unity Hub & Editor: Version 2021.3 LTS or newer. Download Unity
- uv (Python package manager):
- An MCP Client:
- Claude Desktop
- Claude Code
- Cursor
- Visual Studio Code Copilot
- Windsurf
- (Others may work with manual config)
- For Strict validation level that catches undefined namespaces, types, and methods: Method 1: NuGet for Unity (Recommended)
- Install NuGetForUnity
- Go to
Window > NuGet Package Manager
- Search for
Microsoft.CodeAnalysis.CSharp
and install the package - Go to
Player Settings > Scripting Define Symbols
- Add
USE_ROSLYN
- Restart Unity
Method 2: Manual DLL Installation
- Download Microsoft.CodeAnalysis.CSharp.dll and dependencies from NuGet
- Place DLLs in
Assets/Plugins/
folder - Ensure .NET compatibility settings are correct
- Add
USE_ROSLYN
to Scripting Define Symbols - Restart Unity
Note: Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.
🌟Step 1: Install the Unity Package🌟
To install via Git URL
- Open your Unity project.
- Go to
Window > Package Manager
. - Click
+
->Add package from git URL...
. - Enter:
- Click
Add
. - The MCP server is installed automatically by the package on first run or via Auto-Setup. If that fails, use Manual Configuration (below).
To install via OpenUPM
- Instal the OpenUPM CLI
- Open a terminal (PowerShell, Terminal, etc.) and navigate to your Unity project directory
- Run
openupm add com.coplaydev.unity-mcp
Note: If you installed the MCP Server before Coplay's maintenance, you will need to uninstall the old package before re-installing the new one.
Step 2: Configure Your MCP Client
Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below).
Option A: Auto-Setup (Recommended for Claude/Cursor/VSC Copilot)
- In Unity, go to
Window > MCP for Unity
. - Click
Auto-Setup
. - Look for a green status indicator 🟢 and "Connected ✓". (This attempts to modify the MCP Client's config file automatically).
- VSCode: uses
Code/User/mcp.json
with top-levelservers.unityMCP
and"type": "stdio"
. On Windows, MCP for Unity writes an absoluteuv.exe
(prefers WinGet Links shim) to avoid PATH issues. - Cursor / Windsurf (help link): if
uv
is missing, the MCP for Unity window shows "uv Not Found" with a quick [HELP] link and a "Chooseuv
Install Location" button. - Claude Code (help link): if
claude
isn't found, the window shows "Claude Not Found" with [HELP] and a "Choose Claude Location" button. Unregister now updates the UI immediately.
Option B: Manual Configuration
If Auto-Setup fails or you use a different client:
- Find your MCP Client's configuration file. (Check client documentation).
- Claude Example (macOS):
~/Library/Application Support/Claude/claude_desktop_config.json
- Claude Example (Windows):
%APPDATA%\Claude\claude_desktop_config.json
- Claude Example (macOS):
- Edit the file to add/update the
mcpServers
section, using the exact paths from Step 1.
VSCode (all OS)
On Windows, set command
to the absolute shim, e.g. C:\\Users\\YOU\\AppData\\Local\\Microsoft\\WinGet\\Links\\uv.exe
.
Windows:
(Remember to replace YOUR_USERNAME and use double backslashes \)
macOS:
(Replace YOUR_USERNAME if using ~/bin)
Linux:
(Replace YOUR_USERNAME)
For Claude Code
If you're using Claude Code, you can register the MCP server using these commands:
macOS:
Windows:
Usage ▶️
- Open your Unity Project. The MCP for Unity package should connect automatically. Check status via Window > MCP for Unity.
- Start your MCP Client (Claude, Cursor, etc.). It should automatically launch the MCP for Unity Server (Python) using the configuration from Installation Step 2.
- Interact! Unity tools should now be available in your MCP Client. Example Prompt:
Create a 3D player controller
,Create a yellow and bridge sun
,Create a cool shader and apply it on a cube
.
Future Dev Plans (Besides PR) 📝
🔴 High Priority
- Asset Generation Improvements - Enhanced server request handling and asset pipeline optimization
- Code Generation Enhancements - Improved generated code quality and error handling
- Robust Error Handling - Comprehensive error messages, recovery mechanisms, and graceful degradation
- Remote Connection Support - Enable seamless remote connection between Unity host and MCP server
- Documentation Expansion - Complete tutorials for custom tool creation and API reference
🟡 Medium Priority
- Custom Tool Creation GUI - Visual interface for users to create and configure their own MCP tools
- Advanced Logging System - Logging with filtering, export, and debugging capabilities
🟢 Low Priority
- Mobile Platform Support - Extended toolset for mobile development workflows and platform-specific features
- Easier Tool Setup
- Plugin Marketplace - Community-driven tool sharing and distribution platform
- Shader Generation - Generate shaders using CGProgram template
- Advanced Script Validation - Multi-level validation with semantic analysis, namespace/type checking, and Unity best practices (Will need Roslyn Installed, see Prerequisite).
🔬 Research & Exploration
- AI-Powered Asset Generation - Integration with AI tools for automatic 3D models, textures, and animations
- Real-time Collaboration - Live editing sessions between multiple developers (Currently in progress)
- Analytics Dashboard - Usage analytics, project insights, and performance metrics
- Voice Commands - Voice-controlled Unity operations for accessibility
- AR/VR Tool Integration - Extended support for immersive development workflows
For Developers 🛠️
Development Tools
If you're contributing to MCP for Unity or want to test core changes, we have development tools to streamline your workflow:
- Development Deployment Scripts: Quickly deploy and test your changes to MCP for Unity Bridge and Python Server
- Automatic Backup System: Safe testing with easy rollback capabilities
- Hot Reload Workflow: Fast iteration cycle for core development
- More coming!
📖 See README-DEV.md for complete development setup and workflow documentation.
Contributing 🤝
Help make MCP for Unity better!
- Fork the main repository.
- Create a branch (
feature/your-idea
orbugfix/your-fix
). - Make changes.
- Commit (feat: Add cool new feature).
- Push your branch.
- Open a Pull Request against the main branch.
Troubleshooting ❓
- Unity Bridge Not Running/Connecting:
- Ensure Unity Editor is open.
- Check the status window: Window > MCP for Unity.
- Restart Unity.
- MCP Client Not Connecting / Server Not Starting:
- Verify Server Path: Double-check the --directory path in your MCP Client's JSON config. It must exactly match the location where you cloned the UnityMCP repository in Installation Step 1 (e.g., .../Programs/UnityMCP/UnityMcpServer/src).
- Verify uv: Make sure
uv
is installed and working (pip show uv). - Run Manually: Try running the server directly from the terminal to see errors:
# Navigate to the src directory first! cd /path/to/your/UnityMCP/UnityMcpServer/src uv run server.py
- Permissions (macOS/Linux): If you installed the server in a system location like /usr/local/bin, ensure the user running the MCP client has permission to execute uv and access files there. Installing in ~/bin might be easier.
- Auto-Configure Failed:
- Use the Manual Configuration steps. Auto-configure might lack permissions to write to the MCP client's config file.
Still stuck? Open an Issue or Join the Discord!
License 📜
MIT License. See LICENSE file.
Star History
Sponsor
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A bridge enabling seamless communication between Unity and Large Language Models via the Model Context Protocol, allowing developers to automate workflows, manipulate assets, and control the Unity Editor programmatically.
- Key Features 🚀
- How It Works 🤔
- Installation ⚙️
- Usage ▶️
- Contributing 🤝
- Troubleshooting ❓
- License 📜
- Contact 👋
- Acknowledgments 🙏
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA universal Model Context Protocol implementation that serves as a semantic layer between LLMs and 3D creative software, providing a standardized interface for interacting with various Digital Content Creation tools through a unified API.Last updated -12512PythonApache 2.0
- -securityFlicense-qualityA Model Context Protocol server for Unity game development that enables users to manage projects, edit scenes, create prefabs, and generate scripts through natural language integration with Smithery.ai.Last updated -TypeScript
- -securityFlicense-qualityA unified Model Context Protocol Gateway that bridges LLM interfaces with various tools and services, providing OpenAI API compatibility and supporting both synchronous and asynchronous tool execution.Last updated -1Python
- -securityFlicense-qualityTypeScript implementation of the Model Context Protocol that standardizes how LLMs connect to data sources and tools, eliminating vendor lock-in and simplifying AI integration.Last updated -1TypeScript