Weird Unity MCP Server

A custom Model Context Protocol (MCP) server for Unity Editor that provides GameObject and Animation manipulation tools.

Overview

This MCP server allows AI assistants (like Claude) to interact with Unity Editor through a file-based JSON-RPC protocol. It enables creating, modifying, and managing GameObjects and animations directly from an AI chat interface.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant (Claude/GPT)                │
└────────────────────────────┬────────────────────────────────┘
                             │ MCP over stdio
                             ▼
┌─────────────────────────────────────────────────────────────┐
│              Python MCP Server (weird-unity-mcp)            │
│  • set_unity_project_root()                                  │
│  • list_unity_projects()                                     │
│  • GameObject tools (12 tools)                               │
│  • Animation tools (12 tools)                                │
└────────────────────────────┬────────────────────────────────┘
                             │ File-based JSON-RPC
                             ▼
┌─────────────────────────────────────────────────────────────┐
│              Temp/WeirdUnityMcp/                             │
│         req_<uuid>.json  →  response_<uuid>.json            │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│            Unity Editor Plugin (C#)                         │
│  • GameObject handlers                                       │
│  • Animation handlers                                        │
└─────────────────────────────────────────────────────────────┘

Requirements

• Python 3.11+
• Unity 2022.3+
• Operating System: Windows, macOS, or Linux

Installation

Python MCP Server

# Navigate to the project directory
cd E:\Haha\WeirdUnityMcpServer

# Install in development mode
pip install -e .

Unity Plugin

1. Copy the unity-plugin/Assets/WeirdUnityMcp folder to your Unity project's Assets/ folder
2. Unity will automatically compile the scripts
3. Open the server window: Tools > Weird Unity MCP Server

Usage

Starting the Server

Python Side:

weird-unity-mcp

Unity Side:

• Open Unity Editor with your project
• The server auto-initializes on startup
• Or open Tools > Weird Unity MCP Server

MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop) with:

{
  "mcpServers": {
    "weird-unity": {
      "command": "weird-unity-mcp",
      "env": {
        "WEIRDMCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Available Tools

Core Tools

Tool	Description
set_unity_project_root	Set the Unity project path (call first)
list_unity_projects	List all running Unity Editor instances

GameObject Tools (12 tools)

Tool	Description
create_gameobject	Create a new GameObject
delete_gameobject	Delete a GameObject
set_transform	Set position, rotation, scale
parent_gameobject	Parent a GameObject to another
add_component	Add a component to a GameObject
get_component_property	Get a component property value
set_component_property	Set a component property value
find_gameobject	Find GameObjects by name
duplicate_gameobject	Duplicate a GameObject
create_prefab	Create a prefab from a GameObject
instantiate_prefab	Instantiate a prefab into the scene
list_gameobjects	List all GameObjects in the scene
rename_gameobject	Rename a GameObject

Animation Tools (12 tools)

Tool	Description
create_animation_clip	Create a new AnimationClip
create_animator_controller	Create a new AnimatorController
add_keyframe	Add a keyframe to an AnimationClip
set_curve	Set an animation curve with keyframes
add_animation_state	Add a state to an AnimatorController
add_transition	Add a transition between states
set_transition_condition	Add a condition to a transition
add_animator_parameter	Add a parameter to an AnimatorController
set_animator_parameter	Set a parameter value on an Animator
get_animation_clips	Get all AnimationClips from an Animator
set_animation_speed	Set animation playback speed
play_animation	Play an animation state
set_animation_wrap_mode	Set wrap mode for an AnimationClip
get_animation_state_name	Get current animation state

Example Usage

In your AI chat:

# Set the Unity project first
set_unity_project_root("C:/MyUnityProject")

# Create a GameObject
create_gameobject(name="Player", position="0,1,0")

# Add a Rigidbody component
add_component(gameobject_path="Player", component_type="Rigidbody")

# Create an animation
create_animation_clip(name="Walk", save_path="Assets/Animations")

# Add keyframes
add_keyframe(clip_path="Assets/Animations/Walk.anim", property_path="m_LocalPosition.x", time=0, value="0")
add_keyframe(clip_path="Assets/Animations/Walk.anim", property_path="m_LocalPosition.x", time=1, value="5")

Project Structure

weird-unity-mcp/
├── weird_unity_mcp/           # Python package
│   ├── __init__.py
│   ├── __main__.py
│   ├── client.py              # Unity RPC client
│   ├── discovery.py           # Unity process discovery
│   ├── server.py              # MCP server entry point
│   └── tools/
│       ├── gameobject.py      # GameObject tools
│       └── animation.py       # Animation tools
├── unity-plugin/              # Unity C# plugin
│   └── Assets/WeirdUnityMcp/
│       └── Editor/
│           ├── Core/          # Core handler and models
│           └── Handlers/      # Request handlers
│               ├── GameObject/
│               └── Animation/
├── pyproject.toml
└── README.md

Development

Python Development

# Install with dev dependencies
pip install -e .

# Run with debug logging
WEIRDMCP_LOG_LEVEL=DEBUG weird-unity-mcp

# Run with file logging
WEIRDMCP_LOG_FILE=mcp.log WEIRDMCP_LOG_LEVEL=INFO weird-unity-mcp

Unity Development

All Unity scripts are in Assets/WeirdUnityMcp/Editor/:

• Core/McpModels.cs - Request/response models
• Core/McpRequestHandler.cs - Main request router
• Core/WeirdUnityMcpEditor.cs - Editor window
• Handlers/GameObject/ - GameObject operation handlers
• Handlers/Animation/ - Animation operation handlers

Adding New Tools

Python Side (tools/*.py)

@mcp.tool()
async def my_new_tool(param1: str, param2: float = 1.0) -> dict:
    """Description of what this tool does."""
    return await client.execute_request("my_new_tool", {
        "param1": param1,
        "param2": str(param2)
    })

Unity Side (Handlers/*/*Handler.cs)

public static Core.McpResponse MyNewHandler(Core.McpRequest request)
{
    try
    {
        string param1 = request.GetParam("param1", "");
        // ... do work ...

        return Core.McpResponse.Success(request.id,
            new Core.McpResult("Operation successful"));
    }
    catch (Exception e)
    {
        return Core.McpResponse.Error(request.id, e.Message);
    }
}

Then add routing in McpRequestHandler.RouteToHandler():

case "my_new_tool":
    return Handlers.MyCategory.MyNewHandler(request);

Troubleshooting

Server not responding

• Check Unity Editor is running with the project open
• Verify set_unity_project_root() was called
• Check the request directory exists: {ProjectRoot}/Temp/WeirdUnityMcp/

Tools not available

• Restart the MCP server
• Verify Unity plugin compiled (check Console)
• Check for Python errors in logs

Communication timeout

• Default timeout is 30 seconds
• Unity might be processing heavy operations
• Check Unity Console for errors

License

MIT License

Credits

Inspired by the Coplay MCP Server architecture.