Unity MCP Integration for AI Agents

Overview

This package provides a seamless integration between Model Context Protocol (MCP) and Unity Editor, enabling AI assistants to interact with Unity projects in real-time. AI assistants can access scene hierarchies, project settings, and execute code directly within the Unity Editor.

Features

• Browse and manipulate project files
• Access real-time Unity project information
• Understand scene hierarchies and game objects
• Execute C# code directly in the Unity Editor
• Monitor logs and errors
• Control Editor play mode
• Wait for code execution

Getting Started

Prerequisites

• Unity 2021.3 or later
• Node.js 18+ (for running the MCP server)

Installation

1. Install Unity Package

Option A: Package Manager (Git URL)

1. Open Unity Package Manager (Window > Package Manager)
2. Click + and select Add package from git URL...
3. Enter the repository URL: https://github.com/quazaai/UnityMCPIntegration.git
4. Click Add

Option B: Import Custom Package

1. Clone the repository or download it as a unityPackage
2. In Unity, go to Assets > Import Package > Custom Package
3. Select the UnityMCPIntegration.unitypackage file

2. Set Up the MCP Server

Option A: Run the Server Directly

1. Navigate to the mcpServer directory
2. Install dependencies:
   bash npm install
3. Run the server:
   bash node build/index.js

Option B: Add to MCP Host Configuration

Add the server to your MCP Host configuration:

{
  "mcpServers": {
    "unity-mcp-server": {
      "command": "node",
      "args": ["path-to-project\\Library\\PackageCache\\com.quaza.unitymcp@d2b8f1260bca\\mcpServer\\mcpServer\\build\\index.js"],
      "env": {
        "MCP_WEBSOCKET_PORT": "5010"
      }
    }
  }
}

Demo Video

Installing via Smithery

Install Unity MCP Integration for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @quazaai/unitymcpintegration --client claude

Usage

Debugging and Monitoring

1. Open the MCP Debug window in Unity: Window > MCP Debug
2. Use the debug window to:
3. Check connection status
4. Test code execution
5. View logs
6. Monitor events

Available Tools

Unity Editor Tools

• get_editor_state: Get Unity project and editor state information
• get_current_scene_info: Get detailed scene information
• get_game_objects_info: Get GameObject information
• execute_editor_command: Execute C# code in the Unity Editor
• get_logs: Retrieve and filter Unity console logs
• verify_connection: Check active Unity Editor connection

Filesystem Tools

• read_file: Read file contents
• read_multiple_files: Read multiple files
• write_file: Create or overwrite files
• edit_file: Make targeted file edits with diff preview
• list_directory: Get directory listings
• directory_tree: Get hierarchical directory view
• search_files: Find files matching a pattern
• get_file_info: Get file or directory metadata
• find_assets_by_type: Find assets of a specific type
• list_scripts: List all C# scripts in the project

Architecture

The integration consists of two main components:

1. Unity Plugin (C#): Provides access to Unity Editor APIs
2. MCP Server (TypeScript/Node.js): Implements the MCP protocol and communicates with the Unity plugin

Communication occurs via WebSocket, transferring JSON messages for commands and data.

File System Access

The integration includes powerful filesystem tools for:

• Browsing, reading, and editing Unity project files
• Creating new files and directories
• Searching for specific files or asset types
• Analyzing project structure
• Making targeted code changes with diff previews

All file operations are restricted to the Unity project directory for security.

Contributing

Contributions are welcome! Follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Development Setup

Unity Side:

• Open the project in Unity
• Modify C# scripts in the UnityMCPConnection/Editor directory

Server Side:

• Navigate to the mcpServer directory
• Install dependencies: npm install
• Make changes to TypeScript files in the src directory
• Build the server: npm run build
• Run the server: node build/index.js

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For issues or questions, file an issue on the GitHub repository.

About

Enable AI Agents to Control Unity

Topics

ai unity mcp game-development unity-mcp

Resources

Readme

Code of Conduct

Code of Conduct