AccelByte Unity MCP Server

An MCP (Model Context Protocol) server that gives AI assistants the tools to generate AccelByte AGS uGUI prefabs in Unity projects, look up AccelByte Unity SDK best practices, search Bytewars C# example components, and configure SDK credentials — all from a Claude Code or Cursor session.

Prerequisites

• Python 3.10+
• Unity Hub with the Unity editor version matching your project (auto-detected from ProjectSettings/ProjectVersion.txt)
• com.accelbyte.ui-tools package installed in the target Unity project (see Installing the Unity Package)

Installation

cd accelbyte-unity-mcp
pip install -r requirements.txt
python server.py

No cache generation step is needed. Unlike the Unreal MCP server, this server talks directly to the live Unity project and editor — there is no offline symbol database to build.

MCP Configuration

Add the server to the .mcp.json at your Unity project root so Claude Code starts it automatically on session load:

{
  "mcpServers": {
    "accelbyte-unity-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["D:\\ags-ai\\accelbyte-unity-mcp\\server.py"]
    }
  }
}

Installing the Unity Package

Copy the embedded package into your Unity project:

Copy-Item -Path "D:\ags-ai\accelbyte-unity-mcp\data\com.accelbyte.ui-tools" `
          -Destination "<YourUnityProject>\Packages\com.accelbyte.ui-tools" `
          -Recurse -Force

Generated project prefabs are written to Assets/AGS/UI/Generated/. Reusable component prefabs go under Assets/AGS/UI/Components/.

Tools

Prefab Generation

Tool	What it does
unity_ui_select_recipe	Pick the right AGS recipe for a feature (login, leaderboard, friends list, etc.)
unity_ui_preflight	One-shot readiness report: style approval, recipe selection, validation blockers, bridge status
unity_ui_validate	Validate a recipe spec file without opening Unity
unity_ui_resolve	Dry-run: resolve recipe → prefab spec without creating any assets
unity_ui_generate	Generate a project-owned uGUI prefab (bridge mode when editor is open, batch mode when closed)
unity_ui_project_components_generate	Generate reusable component prefabs under Assets/AGS/UI/Components/
unity_ui_patch	Patch an existing prefab with narrow property changes
unity_ui_inspect_generated_layout	Inspect generated prefab health (layout, backing class, components, collections)

Style

Tool	What it does
unity_ui_style_discover	Discover uGUI/TMP style assets in the project and optionally approve the style fingerprint

AGS Core Kit

Tool	What it does
unity_ui_kit_inspect	Inspect package-owned AGS kit prefabs against component specs (read-only)
unity_ui_kit_build	Rebuild all AGS core kit prefabs from scratch (bridge or batch mode)

Scene Setup

Tool	What it does
unity_ui_scene_preflight	Check scene readiness: Canvas, EventSystem, input module compatibility, active panels, blockers
unity_ui_scene_setup	Set up Canvas/EventSystem, instantiate generated panels, attach MenuManager, and save the scene

Editor & Bridge

Tool	What it does
unity_editor_status	Detect the expected Unity editor, whether it is running, and whether com.accelbyte.ui-tools is installed
unity_ui_bridge_health	Lightweight health check for the editor bridge at http://127.0.0.1:48758
unity_trigger_recompile	Refresh AssetDatabase and trigger C# script recompilation after writing a backing class
unity_repair_package_cache	Force a clean re-resolve of a stale UPM git-dependency package (hash mismatch or EPERM rename failure)

Backing Class & Entry Candidates

Tool	What it does
unity_ui_verify_backing_class	Validate that [SerializeField] fields in a C# backing class match the spec's cs_bindings
unity_ui_list_entry_candidates	Report approved project prefab candidates for generated list or collection rows

SDK & Example Components

Tool	What it does
get_accelbyte_unity_how_to	AccelByte Unity SDK best-practices guide with C# code templates for a feature topic
search_unity_example_components	Search Bytewars C# source for classes matching a feature; returns ranked metadata and URIs
describe_unity_example_components	Read the actual C# source files returned by search_unity_example_components
unity_install_sdk	Write AccelByte SDK credentials and config files into a Unity project

How the Bridge Works

When Unity is open with com.accelbyte.ui-tools loaded, generation and scene setup go through a localhost HTTP bridge:

http://127.0.0.1:48758

The bridge starts automatically when the editor loads the package. Prefabs generated through it appear in the open project immediately — no editor restart needed.

When Unity is closed, unity_ui_generate and unity_ui_kit_build fall back to Unity batch mode (-batchmode -nographics). The correct Unity executable is matched against ProjectSettings/ProjectVersion.txt. For non-standard installs or CI environments, set UNITY_EDITOR_PATH:

$env:UNITY_EDITOR_PATH = "C:\Program Files\Unity\Hub\Editor\6000.4.9f1\Editor\Unity.exe"

If the editor is running but the bridge is not reachable (script compilation in progress, package not yet loaded), the MCP returns an actionable error — it will not launch a competing batch instance against an open project.

Typical Workflow

1. Check the editor — unity_editor_status confirms Unity is running and the package is installed.
2. Select a recipe — unity_ui_select_recipe with a natural-language feature description returns a spec stub.
3. Preflight — unity_ui_preflight validates style approval, recipe fit, entry candidates, and bridge readiness in one call.
4. Write a C# backing class (if the recipe requires one) — use get_accelbyte_unity_how_to and search_unity_example_components / describe_unity_example_components for SDK patterns and reference implementations.
5. Verify the backing class — unity_ui_verify_backing_class confirms [SerializeField] fields match the spec.
6. Trigger recompile — unity_trigger_recompile imports the new file and starts compilation; poll unity_ui_bridge_health until isCompiling is false.
7. Generate — unity_ui_generate creates the prefab at Assets/AGS/UI/Generated/.
8. Set up the scene — unity_ui_scene_preflight + unity_ui_scene_setup wires the panel into a Canvas with the correct input module and saves the scene.

Project Structure

.
├── server.py                        # MCP server entry point — registers all tools
├── requirements.txt                 # Python dependencies
├── pyproject.toml                   # Package metadata and entry point
├── generate_source_cache.py         # Optional: regenerate Bytewars C# source index
├── data/
│   └── com.accelbyte.ui-tools/      # Unity Editor package (copy into your project's Packages/)
│       ├── Tools/                   # Python UI tools library used by this server
│       ├── Prefabs/                 # Package-owned AGS core kit prefabs
│       └── Specs/                   # Component specs and recipes
└── tests/                           # Python tests

Troubleshooting

Bridge not reachable (unity_ui_bridge_health returns ok: false) Unity is open but the bridge is down. This usually means scripts are still compiling or the package failed to load. Wait for compilation to finish (check the editor status bar), or reimport Packages/com.accelbyte.ui-tools via the Package Manager.

Editor not detected The server matches the Unity version in ProjectSettings/ProjectVersion.txt against known install roots. If your editor is in a non-standard location, set UNITY_EDITOR_PATH to the full path of Unity.exe before starting the server.

Compile errors block generation unity_ui_generate refuses to proceed when the editor reports compile errors. Fix the errors shown in Unity's Console, then call unity_trigger_recompile and wait until isCompiling is false before retrying.

Stale UPM git-package cache (hash mismatch / EPERM rename) A git-URL package dependency (e.g. com.accelbyte.ui-tools pinned via #main in <YourUnityProject>/Packages/manifest.json) can drift out of sync with what Unity has actually resolved, since #main is a moving ref rather than a fixed commit. Two symptoms point to the same root cause:

• Hash mismatch — Packages/packages-lock.json records one hash for <package-name>, but Library/PackageCache/<package-name>@<hash> on disk has a different hash. Package Manager's hash-keyed lookup then fails to find the package it just fetched.
• EPERM rename failure — a resolve or reimport attempt fails with Failed to rename [...PackageCache\.tmp-<pid>-...\move] to [...PackageCache\<package-name>@<hash>] ... error code [EPERM]. This happens when the Unity Editor is still open and its UnityPackageManager subprocess can't atomically swap in the freshly-cloned revision because the live editor still holds file handles on the package's current contents.

Fix: fully close the Unity Editor first (confirm no Unity.exe process remains — e.g. Get-Process Unity on Windows), then call unity_repair_package_cache with projectPath and packageName (e.g. com.accelbyte.ui-tools). It deletes the stale Library/PackageCache/<package-name>@* folder(s) and removes the package's entry from packages-lock.json, leaving every other dependency untouched. Reopen the Unity editor afterward so Package Manager re-resolves the package fresh from the manifest's git ref, then confirm via Window → Package Manager that it appears under In Project with no error icon.

The tool refuses to run while a matching Unity editor process is detected, unless you pass force=true (only do this if you've independently confirmed it's safe). If you'd rather do it by hand instead of through the MCP tool: close Unity, delete the Library/PackageCache/<package-name>@* folder, remove that package's entry from Packages/packages-lock.json, then reopen Unity.

License

ISC