Unity MCP Server

日本語版 README はこちら

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Unity projects programmatically. Supports both Claude Desktop integration and HTTP API for flexible development workflows.

Features

📦 Core Features

• Project Management: Set up and manage Unity projects with automatic validation

• Asset Creation: Create scripts, materials, shaders, and scenes

• Asset Management: Read, list, and update Unity assets

• Build Automation: Multi-platform builds with custom settings

• Render Pipeline Detection: Automatic detection of Built-in, URP, or HDRP

🔧 Material Management

• Material Creation: Auto-detects render pipeline for correct shader selection

• Shader Updates: Change material shaders with GUID management

• Property Editing: Update colors, floats, textures, and vectors

• Batch Conversion: Convert multiple materials to different shaders

• Material Reading: Inspect material properties and shader information

📝 Code Management

• Script Creation: Create C# scripts with proper namespace structure

• Script Updates: Update existing scripts with full content replacement

• Code Analysis: Diff comparison, duplicate class detection

• Namespace Management: Auto-suggest and apply namespaces based on file location

• Compilation Monitoring: Real-time compilation error tracking

🛠️ Advanced Features

• Editor Extensions: Custom windows, inspectors, property drawers

• Shader Creation: Built-in, URP, HDRP, Shader Graph support

• Unity Refresh: Automatic asset database refresh with batch operations

• Diagnostics: Compilation errors, asset validation, editor log analysis

🎨 UI Toolkit Development

• UXML Creation: Create UI layouts with templates (window, document, component)

• USS Styling: Generate stylesheets with themes, utilities, and component styles

• Component System: Create complete UI components with UXML, USS, and C# controller

• File Management: Read, update, and list UXML/USS files

• UI Builder Integration: Files compatible with Unity's visual UI Builder tool

Installation

# Clone the repository
git clone https://github.com/zabaglione/unity-mcp-server.git
cd unity-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Usage Options

Option 1: Claude Desktop (MCP stdio)

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-unity": {
      "command": "node",
      "args": ["/absolute/path/to/unity-mcp/build/index.js"]
    }
  }
}

Then use natural language in Claude Desktop:

• "Set Unity project to /path/to/project"

• "Create a 2D platformer with inventory system"

• "Generate a player controller with double jump"

Option 2: HTTP Server

1. Start the HTTP server:

npm run start:http
# or specify a custom port
PORT=8080 npm run start:http

2. Set up your Unity project:

curl -X POST http://localhost:3000/api/project/setup \
  -H "Content-Type: application/json" \
  -d '{"projectPath": "/path/to/your/unity/project"}'

3. Analyze requirements with AI:

curl -X POST http://localhost:3000/api/ai/analyze \
  -H "Content-Type: application/json" \
  -d '{"description": "Create a 2D platformer with inventory system"}'

Documentation

• API Documentation - Complete HTTP API reference

• Available Tools - List of all MCP tools

• Critical Features - ⚠️ MUST READ: Essential features for proper Unity integration

• Documentation Index - All documentation

Key Endpoints

• GET /health - Health check

• GET /api-docs - API documentation

• POST /api/project/setup - Configure Unity project

• POST /api/ai/analyze - Analyze requirements

• POST /api/system/player-controller - Generate player controller

• POST /api/asset/create-script - Create C# scripts

• POST /api/batch - Execute batch operations

Usage Examples

Create a Player Controller

const response = await fetch('http://localhost:3000/api/system/player-controller', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    gameType: 'platformer',
    requirements: ['doubleJump', 'wallJump', 'dash']
  })
});

Generate Project Structure

const response = await fetch('http://localhost:3000/api/project/create-structure', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    projectType: '2D_Platformer',
    customStructure: {
      folders: ['Scripts/Player', 'Scripts/Enemy', 'Scripts/UI']
    }
  })
});

UI Toolkit Examples

Important: Effective Prompt Patterns

For best results with UI Toolkit, use specific keywords like "UI Toolkit panel component" or mention file types (UXML, USS).

Create a Game HUD

# ✅ Recommended - Specific component type
"Create a UI Toolkit panel component named GameHUD with health bar, score display, and minimap"

# ✅ Recommended - Explicit file types
"Create GameHUD.uxml, GameHUD.uss, and GameHUDController.cs for a game HUD with health bar"

# The server will create:
# 1. GameHUD.uxml with proper layout
# 2. GameHUD.uss with styling
# 3. GameHUD.cs controller to manage the UI

Create a Settings Menu

# ✅ Recommended approach
"Create a UI Toolkit panel component named SettingsMenu with graphics, audio, and controls tabs"

# Alternative: Specify component type
"Create a form component called SettingsMenu using UI Toolkit"

# Creates:
# - SettingsMenu.uxml with tab navigation
# - SettingsMenu.uss with professional styling
# - SettingsMenu.cs with tab switching logic

Create Custom UI Components

# ✅ Specify component type for better recognition
"Create a UI Toolkit button component named CustomButton with hover effects"

# Create an inventory system
"Create a UI Toolkit panel component named InventorySystem with item slots and drag-drop support"

# Create a dialog system
"Create a UI Toolkit modal component named DialogBox with typewriter effect"

Update Existing UI

# Update UXML layout
"Update the MainMenu.uxml to add a credits button"

# Update USS styles
"Update GameTheme.uss to use a dark color scheme"

# Read UI files
"Show me the current HUD.uxml layout"
"Read the styles from GameTheme.uss"

Step-by-Step Approach (if automatic detection fails)

# Create files individually
"1. Create HUD.uxml for UI Toolkit"
"2. Create HUD.uss for styling"
"3. Create HUDController.cs for the UI logic"

UI Toolkit Troubleshooting

If UI Toolkit commands only create C# scripts instead of UXML/USS files:

1. Use specific component types: "UI Toolkit panel component" works better than just "UI Toolkit"

2. Name the component explicitly: "Create a UI Toolkit panel component named GameHUD"

3. Mention file types: "Create GameHUD.uxml and GameHUD.uss"

4. Use the step-by-step approach if automatic detection fails

Recent Updates

v2.3.0 (2025-06-13)

• Added full UI Toolkit support

• UXML/USS file creation, reading, and updating

• Complete UI component creation (UXML + USS + C#)

• Multiple UI templates (button, panel, list, form, card, modal)

• Theme system and utility styles support

Development

# Run in development mode
npm run dev

# Run tests
npm test

# Clean build
npm run clean

Configuration

Environment Variables

• PORT - HTTP server port (default: 3000)

• UNITY_PATH - Path to Unity executable (auto-detected if not set)

Supported Platforms

• macOS

• Windows

• Linux

Unity Versions

• Unity 2021.3 LTS and newer

• Unity 6000.x (Unity 6)

Architecture

The server uses a modular service architecture:

• AI Core - Natural language processing and planning

• Service Layer - Unity project operations

• HTTP API - RESTful endpoints

• Template System - Code generation templates

Requirements

• Node.js 18.x or higher

• Unity 2021.3 LTS or newer

• npm or yarn

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

Built with:

• Express.js for HTTP server

• TypeScript for type safety

• Unity Editor integration

Support

For issues and feature requests, please use the GitHub issue tracker.

For direct tool usage, here are the available MCP tools:

Project Management

• project_setup_path - Set Unity project path

• project_read_info - Get project information

Asset Creation & Management

• asset_create_script - Create C# scripts

• asset_read_script - Read script contents

• asset_update_script - Update script content

• asset_list_scripts - List all scripts

• asset_create_scene - Create Unity scenes

• asset_create_shader - Create shaders (builtin, URP, HDRP, ShaderGraph)

• asset_read_shader - Read shader content

• asset_update_shader - Update shader content

• asset_list_shaders - List all shaders

• asset_list_all - List all assets by type

Editor Extensions

• editor_create_script - Create editor scripts

• editor_list_scripts - List editor scripts

Material Management

• asset_create_material - Create materials with auto-detected render pipeline

• asset_create_material_with_shader - Create material with specific shader

• asset_update_material_shader - Change material shader

• asset_update_material_properties - Update material properties

• asset_read_material - Read material properties

• asset_update_material - Update entire material content (YAML)

• asset_clone_material - Clone material with new name

• asset_batch_convert_materials - Batch convert materials

• asset_list_materials - List all materials

Code Analysis

• code_analyze_diff - Get detailed diff between files

• code_detect_duplicates - Detect duplicate class names

• code_suggest_namespace - Suggest namespace for file

• code_apply_namespace - Apply namespace to script

Compilation Tools

• compile_get_errors - Get compilation errors with context

• compile_get_status - Get current compilation status

• compile_install_helper - Install compilation monitoring helper

Build Operations

• build_execute_project - Build Unity project

System Operations

• system_setup_refresh - Setup Unity refresh handler

• system_refresh_assets - Refresh Unity assets

• system_batch_start - Start batch mode

• system_batch_end - End batch mode

UI Toolkit Operations

• ui_create_uxml - Create UXML layout files

• ui_create_uss - Create USS style files

• ui_update_uxml - Update existing UXML content

• ui_update_uss - Update existing USS content

• ui_read_uxml - Read UXML file content

• ui_read_uss - Read USS file content

• ui_list_uxml - List all UXML files

• ui_list_uss - List all USS files

• ui_create_component - Create complete UI component (UXML + USS + C#)

Supported Build Targets

• StandaloneWindows64

• StandaloneOSX

• StandaloneLinux64

• iOS

• Android

• WebGL

Development

Scripts

• npm run build - Build the TypeScript project

• npm run dev - Watch mode for development

• npm start - Run the built server

• npm run clean - Clean build directory

• npm run test - Run automated tests (when implemented)

• npm run test:manual - Instructions for manual testing

Project Structure

mcp-server-unity/
├── src/
│   ├── server.ts                 # Main server implementation
│   ├── config/                   # Configuration files
│   ├── services/                 # Service layer (modular architecture)
│   │   ├── project-service.ts    # Unity project management
│   │   ├── script-service.ts     # Script operations
│   │   ├── asset-service.ts      # Asset creation
│   │   ├── shader-service.ts     # Shader management
│   │   ├── editor-script-service.ts  # Editor extensions
│   │   ├── material-service.ts   # Material management
│   │   ├── code-analysis-service.ts  # Code analysis tools
│   │   ├── compilation-service.ts    # Compilation monitoring
│   │   ├── build-service.ts      # Build automation
│   │   └── unity-refresh-service.ts  # Unity refresh system
│   ├── templates/                # Code generation templates
│   ├── types/                    # TypeScript type definitions
│   ├── utils/                    # Utility functions
│   └── validators/               # Input validation
├── tests/
│   ├── comprehensive-test.js     # Full feature test suite
│   ├── integration-test.js       # Integration tests
│   └── run-manual-tests.sh      # Manual test runner
├── build/                        # Compiled output (gitignored)
├── package.json                  # Project configuration
├── tsconfig.json                 # TypeScript configuration
├── setup.sh                      # Setup script
└── REGRESSION_TEST_CASES.md      # Detailed test documentation

Troubleshooting

Unity project not recognized

• Ensure the project path contains both Assets and ProjectSettings folders

• Check file permissions

Build command fails

• Verify Unity is installed at the expected location

• For custom Unity installations, modify the Unity path in your fork

Script not found

• Scripts are searched recursively from the Assets folder

• Ensure the file has a .cs extension

Testing

The project includes comprehensive test cases with 100% feature coverage:

Comprehensive Test Suite

# Run all feature tests (38 test cases)
node tests/comprehensive-test.js /path/to/unity/project

# Example
node tests/comprehensive-test.js /Users/me/Unity/MyProject

Automated Integration Tests

# Run integration tests with your Unity project
npm run test:integration /path/to/unity/project

# Example
npm run test:integration /Users/me/Unity/MyProject

Manual Testing

# Run guided manual tests
./tests/run-manual-tests.sh /path/to/unity/project

Test Coverage

• 38 automated test cases covering all features

• 10 test categories: Project, Scripts, Assets, Shaders, Editor, ProBuilder, Packages, Refresh, Build, Errors

• Automatic cleanup after test execution

• Performance metrics for each test

• Test Documentation: See tests/README.md for testing guide

• Test Cases: Comprehensive test coverage in tests/ directory

Recent Updates

v2.2.0 (2025-06-06)

• Added shader and material update features

• Implemented temporary backup system with automatic cleanup

• Added material cloning functionality

• Enhanced shader GUID caching and lookup

• Added comprehensive read operations for shaders

v2.1.0 (2025-06-06)

• Fixed shader-material GUID reference issues

• Added meta file generation for all Unity assets

• Improved custom shader detection and lookup

• Enhanced material creation with proper shader references

• Added comprehensive debugging and logging

See CHANGELOG.md for full version history.

Known Issues and Solutions

Custom Shader References

When creating custom shaders, use the full shader name (including "Custom/" prefix) when creating materials:

# Create shader
asset_create_shader shaderName:"MyShader" shaderType:"builtin"
# Returns: Shader Name: Custom/MyShader

# Create material with that shader
asset_create_material_with_shader materialName:"MyMaterial" shaderName:"Custom/MyShader"

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

Repository

Recommended repository name: mcp-server-unity

This follows the MCP ecosystem naming convention where MCP servers are prefixed with mcp-server-.

License

MIT License - see LICENSE file for details.