Skip to main content
Glama
Sign In

MCP Server for Unity

by zabaglione
GitHub
TypeScript
MIT License
3
  • Linux
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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
  1. 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"}'
  1. 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

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'] } }) });

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

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.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A Model Context Protocol server that enables Claude to interact directly with Unity projects, providing tools for script creation, asset management, and project building.

  1. Features
    1. 📦 Core Features
    2. 🔧 Material Management
    3. 📝 Code Management
    4. 🛠️ Advanced Features
  2. Installation
    1. Usage Options
      1. Option 1: Claude Desktop (MCP stdio)
      2. Option 2: HTTP Server
    2. Documentation
      1. Key Endpoints
    3. Usage Examples
      1. Create a Player Controller
      2. Generate Project Structure
    4. Development
      1. Configuration
        1. Environment Variables
        2. Supported Platforms
        3. Unity Versions
      2. Architecture
        1. Requirements
          1. Contributing
            1. License
              1. Acknowledgments
                1. Support
                  1. Project Management
                  2. Asset Creation & Management
                  3. Editor Extensions
                  4. Material Management
                  5. Code Analysis
                  6. Compilation Tools
                  7. Build Operations
                  8. System Operations
                2. Supported Build Targets
                  1. Development
                    1. Scripts
                    2. Project Structure
                  2. Troubleshooting
                    1. Unity project not recognized
                    2. Build command fails
                    3. Script not found
                  3. Testing
                    1. Comprehensive Test Suite
                    2. Automated Integration Tests
                    3. Manual Testing
                    4. Test Coverage
                  4. Recent Updates
                    1. v2.2.0 (2025-06-06)
                    2. v2.1.0 (2025-06-06)
                  5. Known Issues and Solutions
                    1. Custom Shader References
                  6. Contributing
                    1. Repository
                      1. License

                        Related MCP Servers

                        • Linear MCP Server

                          cpropster
                          -
                          security
                          A
                          license
                          -
                          quality
                          A Model Context Protocol server that allows Claude to interact with Linear's API for managing teams, issues, projects, and cycles.
                          Last updated -
                          18
                          1
                          TypeScript
                          MIT License

                        • API Tester MCP Server

                          Vikrant-Khedkar
                          -
                          security
                          F
                          license
                          -
                          quality
                          A Model Context Protocol server that allows Claude to make API requests on your behalf, providing tools for testing various APIs including HTTP requests and OpenAI integrations without sharing your API keys in the chat.
                          Last updated -
                          Python
                          • Linux
                          • Apple

                        • Bonsai-mcp

                          JotaDeRodriguez
                          -
                          security
                          A
                          license
                          -
                          quality
                          A Model Context Protocol server that integrates Claude with Blender, enabling users to analyze and interact with IFC (Industry Foundation Classes) building models through natural language commands.
                          Last updated -
                          9
                          Python
                          MIT License
                          • Apple

                        • UIThub MCP Server

                          janwilmake
                          -
                          security
                          F
                          license
                          -
                          quality
                          Model Context Protocol server that enables Claude to retrieve and analyze code from GitHub repositories through the uithub API.
                          Last updated -
                          22
                          9
                          JavaScript

                        View all related MCP servers

                        New MCP Servers

                        MCP directory API

                        We provide all the information about MCP servers via our MCP API.

                        curl -X GET 'https://glama.ai/api/mcp/v1/servers/zabaglione/mcp-server-unity'

                        If you have feedback or need assistance with the MCP directory API, please join our Discord server