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 6. The package is tested on Windows with Unity 6000.0.84f1, 6000.1.17f1, 6000.3.13f1 and 6000.6.3f1

• 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)

Related MCP server: Unity-MCP

Installation

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

All tools work with no build step. The example code search (search_unity_example_components and describe_unity_example_components) uses a copy of the SDK code from Byte Wars 1.9.8, which uses AccelByte Unity SDK 17.17.0. This copy ships with the server, together with its license (data/examples/bytewars/LICENSE.md).

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": ["<PathToRepo>\\accelbyte-unity-mcp\\server.py"]
    }
  }
}

Installing the Unity Package

Copy the embedded package into your Unity project:

Copy-Item -Path "<PathToRepo>\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

Style

AGS Core Kit

Scene Setup

Editor & Bridge

Backing Class & Entry Candidates

SDK & Example Components

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 = "<PathToUnityHubEditor>\<YourUnityVersion>\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         # Copies the Byte Wars SDK example code into data/examples/bytewars/
├── data/
│   ├── best-practices.json          # SDK how-to guides
│   ├── examples/bytewars/           # Byte Wars SDK example code and its search index
│   └── 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

Updating the Byte Wars examples

To move the example code to a new Byte Wars release:

1. Clone https://github.com/AccelByte/accelbyte-unity-bytewars-game.

2. Run python generate_source_cache.py --bytewars-repo <PathToClone> --ref <ReleaseTag>.

3. Run the tests and commit the changes in data/examples/bytewars/.

The script reads the files from the release tag with git, so local changes in the clone do not get into the copy. It keeps only the module code that calls the SDK, and skips the *_Starter.cs tutorial files. It also copies the Byte Wars LICENSE.md from the tag, and stops with an error if the tag has no license or the SDK version is not a #tag in Packages/manifest.json.

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

Apache-2.0

See LICENSE and NOTICE. The Byte Wars example code under data/examples/bytewars/ is not covered by this license; it keeps its own license, data/examples/bytewars/LICENSE.md.