Create Your First Unity Biome MCP Plugin¶

my-unity-plugin/
  python/
    pyproject.toml
    src/my_plugin/
      plugins/
        __init__.py
        my_tools.py
  unity/
    Editor/
      MyMCPPlugin.cs

[project]
name = "my-unity-plugin"
version = "0.1.0"
dependencies = ["unity-biome-mcp"]

[project.entry-points."unity_mcp.plugins"]
my_tools = "my_plugin.plugins.my_tools"

from unity_mcp.plugin_api import RO, register_tools

_MY_TOOLS = {"my_count_objects"}

def register(mcp, send, args):
    @mcp.tool(annotations=RO)
    async def my_count_objects(name_filter: str = "") -> str:
        """Count GameObjects matching a name filter."""
        return await send("my_count_objects", args(name_filter=name_filter))

    register_tools("my_plugin", _MY_TOOLS)

using UnityEditor;
using UnityMCP.Editor;

namespace MyPlugin.Editor
{
    [InitializeOnLoad]
    public class MyMCPPlugin : IMCPPlugin
    {
        public string Name => "MyPlugin";
        public string CommandPrefix => "my_";

        static MyMCPPlugin() => PluginRegistry.Register(new MyMCPPlugin());

        public void RegisterCommands()
        {
            CommandRegistry.Register("my_count_objects", args =>
            {
                var filter = JsonHelper.ExtractString(args, "name_filter");
                var objects = string.IsNullOrEmpty(filter)
                    ? UnityEngine.Object.FindObjectsOfType<UnityEngine.GameObject>()
                    : System.Array.FindAll(
                        UnityEngine.Object.FindObjectsOfType<UnityEngine.GameObject>(),
                        go => go.name.Contains(filter));
                // Build response manually — JsonHelper.FormatResponse is internal.
                // Return plain text; the framework wraps it in the wire protocol.
                return $"count: {objects.Length}";
            });
        }

        public void OnDomainReload() { }

        // Organize tools into subcategories (v0.56.0+)
        public string GetToolSubcategory(string toolName)
        {
            return toolName switch
            {
                "my_count_objects" => "Scene",
                _ => null  // Top-level placement
            };
        }
    }
}

# Python (make it discoverable)
cd my-unity-plugin/python && pip install -e .

# C# — symlink into game project (Unix/macOS)
ln -s /path/to/my-unity-plugin/unity/Editor /path/to/game-project/Assets/MyPlugin/Editor

# Windows: use mklink (run as Administrator in cmd.exe)
# mklink /D "C:\path\to\game-project\Assets\MyPlugin\Editor" "C:\path\to\my-unity-plugin\unity\Editor"
# Or just copy the Editor folder directly instead of symlinking.

# Force MCP server reload
# Open MCP > Status in Unity and select Restart, then restart the Claude Code CLI session

# tests/test_my_tools.py
import pytest
from unittest.mock import MagicMock, AsyncMock

@pytest.mark.asyncio
async def test_count_objects():
    mcp = MagicMock()
    tools = {}
    mcp.tool = lambda **kw: lambda fn: tools.update({fn.__name__: fn}) or fn

    send = AsyncMock(return_value="count: 42")
    args = lambda **kw: {k: v for k, v in kw.items() if v is not None}

    from my_plugin.plugins.my_tools import register
    register(mcp, send, args)

    result = await tools["my_count_objects"](name_filter="Player")
    send.assert_awaited_once_with("my_count_objects", {"name_filter": "Player"})
    assert "42" in result