AkerMCP

Aker (Egyptian: ꜣkr) was an ancient Egyptian earth god, depicted as two lions seated back-to-back facing opposite horizons — Sef and Duau (Yesterday and Today) — guarding the sun's safe passage through the underworld. In this architecture, Aker is the bridge: one face speaking JSON-RPC to the LLM, the other manipulating the engine's main thread via IPC.

Give your AI Assistant (Claude, Cursor, Copilot, Antigravity) the power to directly manipulate any C# Game Engine.

Traditionally, AI coding assistants can only suggest code for you to copy-paste. With AkerMCP, you grant your AI the ability to actually see and touch your game project in real-time.

🦁🦁 The only MCP that drives Unity, Godot and Stride as first-class engines — every tool, full parity, across all three.

The 100% C# engine-agnostic core means the same AI workflow — inspect, modify, execute C#, screenshot, build — works identically whether you're in the Unity Editor, Godot, or Stride Game Studio, and ports to Flax Engine or any custom C# engine with a lightweight adapter. No other open-source MCP server exposes this breadth of editor control across three different engines.

🎮 Supported engines — full feature parity

Most rows are implemented and verified live in each engine's editor — not a roadmap. Plus engine-independent OS tools (list_windows / capture_window) to screenshot any window on the machine.

Newest additions — create_sprite lets the AI author flat-geometric placeholder art as a vector spec that the server rasterizes to a PNG and imports as a real sprite, so it works regardless of the engine's own vector support. Unity & Godot import + place it; Stride persists it as a real .sdtex texture asset in the package (plus a runtime preview entity for immediate visibility). Companion authoring tools new_scene/open_scene/save_scene and write_script (all three engines) let an AI build a 2D prototype — art, scene and gameplay code — end-to-end from a single prompt.

(Verified live in Game Studio: create_sprite persists and surfaces a real .sdtex texture asset and places a runtime sprite entity in an open scene; new_scene creates and opens a scene. On Stride, take_screenshot is served by the OS-level window fallback — Game Studio only ticks its embedded editor game on demand, so the internal readback can't reliably run during MCP use; just keep Game Studio non-minimized.)

🧠 No ceiling: arbitrary C# on the editor's main thread

The structured tools are the convenient path — but the real power is the execute tool, which compiles and runs any C# (via Roslyn) directly against the live editor. That means the entire engine + editor API, your own project assemblies, the asset pipeline, the file system — anything the editor itself can do, the AI can do. There are effectively no limits to what it can accomplish.

In short: AkerMCP gives the AI eyes (inspect, query, screenshots) and hands (set, create, call, execute, build) to do whatever you actually need — not a fixed menu of canned operations, but open-ended capability, identically across every supported engine.

🪄 The "Wow" Factor: Talk to your Engine

Imagine asking your AI:

"Hey, make the Player character 20% bigger, turn all enemy materials red, and spawn 50 trees scattered across the ground plane."

• Without AkerMCP: The AI writes a custom script, explains where to put it, you switch to Unity, attach it, press play, and hope it works.
• With AkerMCP: The AI just does it. Instantly. Right inside your editor — Unity, Godot, or Stride. You watch the scene change before your eyes.

AkerMCP acts as a seamless bridge. It allows AI agents to inspect your scene hierarchy, modify objects, and even execute complex procedural C# scripts on the fly. No more manual repetitive clicking in the inspector—just tell your AI what you want to achieve.

Example: "Spawn 10 spheres in a circle with a radius of 10"

for (int i = 0; i < 10; i++) {
    float angle = i * Mathf.PI * 2 / 10f;
    Vector3 pos = new Vector3(Mathf.Cos(angle) * 10f, 0, Mathf.Sin(angle) * 10f);
    GameObject sphere = GameObject.CreatePrimitive(PrimitiveType.Sphere);
    sphere.transform.position = pos;
    sphere.name = $"Aker_Sphere_{i}";
}

The same request, same tools — in Stride Game Studio. The AI duplicated a sphere into a ring via execute (through Stride's asset/Quantum layer, so they're real, selectable, saved entities — note AkerSphere_* in the Scene hierarchy on the left), then captured the editor itself. Identical workflow, different engine:

(Curious about the internal technical details? Jump to the Architecture section).

🏆 Real-World Case Studies

To truly understand the unprecedented power of AkerMCP, consider these two real-world sessions:

Case Study 1: The "Invisible" GPU Bug

A developer's Custom Voxel Ambient Occlusion (AO) was rendering completely flat, making underground caves far too bright.

• Without AkerMCP, an AI assistant is blind. It can only read your shader code, guess what might be wrong, and give you a list of 5 things to check manually. You are left recompiling, entering Play Mode, attaching debuggers, and iterating blindly for hours because the state lives entirely in GPU memory.
• With AkerMCP, the AI sits at your desk:
  1. Visual Verification: By calling take_screenshot on the Scene View, the AI visually confirmed the user's report: "The overall look is flat and washed out. The caves aren't dark at all."
  2. Dynamic Editor Control: The AI wrote an on-the-fly C# Roslyn script via the execute tool to force the VoxelWorldGI pipeline into a pure "Debug 10 (Grayscale AO)" mode. A second screenshot confirmed the AO channel was completely white (AO ≈ 1.0).
  3. CPU Memory Inspection: To check if the voxelization was failing, the AI wrote another script to read the _cells array in CPU memory, counting 29,408 occupied solid voxels. Voxelization was working perfectly.
  4. 3D Texture Readback: Realizing the bug was in the Cone-Tracing pass, the AI wrote a complex script to perform a GPU readback of the Texture3D radiance buffer. Unity only returned the 0-depth slice by default, so the AI rewrote its script to iterate and aggregate all 104 volume layers.
  5. The Smoking Gun: By analyzing the aggregated buffer, the AI discovered the alpha channel was mirroring the raw occupancy data instead of the calculated AO. It immediately pinpointed the exact failure: an empty mip-map chain generation step meant the cones couldn't trace any occlusion.

In just minutes, the AI diagnosed a complex, data-dependent GPU bug. It didn't just write code; it acted as a Technical Artist—triggering Editor pipelines, reading multidimensional arrays from VRAM, taking visual snapshots, and confirming hypotheses through interactive feedback.

Case Study 2: The "Context-Aware" Shader Architect

In another session, the user wanted standard (non-voxel) meshes to react to the lighting data generated by the custom Voxel Engine.

• Without AkerMCP: The AI might provide generic HLSL code. The user would have to manually create the .hlsl include files, figure out how to wire them up to Unity's Shader Graph as Custom Function Nodes, and hope the variable names matched the engine's internals.
• With AkerMCP (and LynxMCP):
  1. The AI searched the project's custom C# and Shader code to understand exactly how the Voxel Engine stored its lighting buffers (e.g. _VoxelGridMipped).
  2. It wrote an HLSL include file specifically tailored to the project's architectural quirks.
  3. Using the execute tool, the AI tapped into Unity's AssetDatabase to automatically create and save the .hlsl files in the correct Assets/ directory.
  4. It didn't stop at the code. Recognizing that Unity Shader Graphs are JSON files under the hood, the AI used the execute tool to programmatically construct and save a complete .shadergraph asset directly into the project. This graph automatically wired up the new HLSL Custom Function Node to the PBR Master node.
  5. Visual A/B Testing (Zero User Input): Finally, the AI didn't just assume it worked. It used execute to create a new Material using the generated shader, spawned two identical test objects in the scene—one with a standard shader, and one with the new Voxel GI shader—and applied the materials itself. It then took a take_screenshot to visually compare them side-by-side, proving the custom Global Illumination was contributing correctly, completely autonomously.

AkerMCP turns the AI from a simple "code generator" into an autonomous Technical Artist that not only writes the shaders, but natively integrates them into the engine's asset pipeline.

🦁 How it Works (Under the Hood)

Traditional MCP integrations for game engines ship 100+ hand-written tools — one per operation, one per component type. Every engine update breaks them.

AkerMCP replaces all of that with 20+ generic tools powered by runtime reflection and Roslyn. A single set_property tool can modify any property on any object in any engine, while the execute tool enables complex procedural generation via C# scripts. The take_screenshot tool closes the loop, giving the AI a way to visually verify what it just changed. The engine-specific adapter provides the necessary layer for interacting directly with the engine's API.

AI: "Set the player's position to (10, 0, 5)"

→ set_property {"object_path": "/Player", "property_path": "position", "value": {"x":10,"y":0,"z":5}}
← Property 'position' set successfully on /Player

No custom tool class needed. No code generation. Just reflection.

Features

• Equal support for every engine — currently Unity, Godot and Stride: not a Unity tool with side ports. All three are first-class adapters at full feature parity (see the table above); none is the "primary" engine, and there is no comparable multi-engine alternative.
• 20+ Generic Reflection-Based Tools: Operate on any object or component without custom tool definitions — the identical tool surface across all engines.
• Roslyn-Powered Dynamic Execution: Send arbitrary C# scripts via the execute tool to perform complex procedural tasks or bulk operations directly inside the editor (Unity / Godot / Stride Game Studio).
• AI-Authored 2D Placeholders (create_sprite): The AI emits a flat-geometric shape-spec (JSON) and the server rasterizes it to an RGBA PNG (pure-managed ImageSharp.Drawing) before importing it as a sprite — engine-agnostic by design, since the engine receives a ready raster and never needs its own SVG/vector support. Perfect for clean prototype art with zero art skills.
• End-to-End Authoring Tools: new_scene/open_scene/save_scene (scene management) and write_script (writes a source file into the project, resolved engine-side) let an AI go from prompt to a playable prototype — scene, art and gameplay code — in one session.
• Visual Verification (take_screenshot): Engine-internal scene-view capture with editor gizmos in all three engines, plus a cross-platform OS-level fallback (PrintWindow on Windows, Quartz CGWindowListCreateImage on macOS) and standalone list_windows / capture_window tools for any window. Output is auto-resized and JPEG-encoded via ImageSharp to fit AI image limits.
• MessagePack IPC Protocol: High-performance, low-latency binary communication between the standalone MCP Server and the engine plugin.
• Robust Type System: Serializes and deserializes engine structs (Vector3, Color, Bounds, …) seamlessly, case-insensitively, for Unity, Godot and Stride alike.
• Engine-Agnostic Core: A shared .NET Standard 2.1 core; adding a fourth engine (Flax, or any custom C# engine) is just another adapter — the server and tools never change.

The Perfect Combo: AkerMCP + LynxMCP

AkerMCP gives your AI agent the hands to manipulate the active scene and execute runtime code. But to be truly effective, the AI also needs the brain to understand your entire project architecture and dependencies.

We highly recommend running AkerMCP alongside LynxMCP, our local RAG (Retrieval-Augmented Generation) server designed for codebases.

When combined, your AI gets a complete global vision:

• LynxMCP provides deep, semantic search over your custom C# scripts and up-to-date Unity/library documentation (feeding the AI with exact APIs and patterns it wouldn't otherwise know from its standard training data).
• AkerMCP uses that exact context to write and execute flawless Roslyn scripts directly in your Editor.

Table of Contents

• The Perfect Combo: AkerMCP + LynxMCP
• Quick Start (Recommended)
• Connecting an AI Client
  • Claude Code (CLI)
  • Claude Desktop
  • Cursor
  • Windsurf
  • Google Antigravity
  • VS Code + Copilot
• Advanced: Building from Source (For Developers)
• Verifying the Connection
• MCP Tools
• MCP Resources
• Type System
• Example Session
• Architecture
• Writing an Engine Adapter
• AI Integration Rules
• Troubleshooting
• License

Quick Start (Recommended)

Two steps: (1) install the adapter for your engine — Unity, Godot, or Stride (they are peers; pick the one you use), then (2) run the standalone MCP server, which is identical for all of them and auto-discovers whichever engine is running.

1a. Unity Setup

You do not need to install the .NET SDK or compile any code for Unity.

1. Go to the latest GitHub Release and download AkerMCP.unitypackage.

2. Open your Unity project and double-click the package to import it. (This package already contains all necessary C# scripts, dependencies, and Roslyn compilers).

3. (Optional) Open the menu AkerMcp → Setup Test Scene to create a ready-to-test scene.

4. Open Window → AkerMcp and click Start AkerMcp Plugin. You should see a green Running status. (Tip: The plugin must be running before you start the server. The server discovers it automatically via a lock file).

   

1b. Godot Setup

AkerMCP ships a Godot 4.x (.NET/C#) adapter with the same full toolset as Unity. Because a Godot project is a real .csproj, there are no DLLs to copy — references and the Roslyn engine come via NuGet/ProjectReference.

1. Download AkerMcp.Godot-addon.zip from the latest Release and extract it so you get addons/aker_mcp/ in your Godot project (or copy this repo's plugins/godot folder into your project as addons/aker_mcp).
2. Add the AkerMcp core to your game's .csproj (or use the included samples/godot project directly — run setup-samples first to link the addon):

   <ProjectReference Include="path/to/AkerMcp.Shared.csproj" />
   <ProjectReference Include="path/to/AkerMcp.Client.csproj" />
   <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Scripting" Version="4.8.0" />
   

   Make sure your project has <EnableDynamicLoading>true</EnableDynamicLoading> (required for editor plugins).
3. Build the C# solution once (Project → Tools → C#: Create/Build), then enable the plugin under Project → Project Settings → Plugins → AkerMcp.

The plugin auto-starts with the editor and pumps requests on the main thread every frame. Scene paths follow the edited scene root (e.g. /TestScene/Box), property paths are case-insensitive (position.x resolves to Position.X), and screenshots capture the editor's 3D viewport. The standalone MCP server discovers the Godot plugin automatically — no server changes needed.

1c. Stride Setup

AkerMCP ships a Stride (Game Studio) adapter with the same full toolset — including undoable edits via Stride's Quantum graph, execute (Roslyn), real Scene-view screenshots (editor back-buffer, with gizmos), and the platform/build tools (dotnet build per executable project).

Stride support runs as a Game Studio editor plugin. Game Studio has no third-party plugin discovery, so AkerMcp registers itself with one tiny bootstrap. Pick the path that matches how you got Stride.

Option A — Stride installed from the Launcher (official binaries, no Stride rebuild) — recommended

A per-launch wrapper injects the plugin only into the Game Studio process it starts, via the .NET runtime's DOTNET_STARTUP_HOOKS. The variable is never written to your user/machine environment, so it cannot affect any other .NET app; if the plugin DLL is ever missing, the wrapper just launches Game Studio without AkerMcp.

# one-time, from the repo root
.\install-stride-wrapper.ps1 -GameStudioPath "C:\path\to\Stride.GameStudio.exe"
# (omit -GameStudioPath to auto-detect a Launcher install)

This builds the adapter against your installed Game Studio, drops it into <GameStudio>/AkerMcpPlugins, and creates a "Stride Game Studio (AkerMCP)" shortcut (Desktop + Start Menu). Launch Stride from that shortcut and open a project + scene — the pipe server starts automatically. Your official Stride shortcut keeps launching Game Studio untouched. Remove everything with .\install-stride-wrapper.ps1 -Uninstall.

Option B — You build Stride Game Studio from source

The adapter loads in-process via a drop-in loader patched into Game Studio itself (no wrapper needed).

1. Build Stride Game Studio from source (the adapter references its editor assemblies). See the Stride build docs.
2. Add a drop-in plugin loader to Stride.GameStudio/Program.cs (right after the built-in plugins are registered) so Game Studio loads any adapter placed in an AkerMcpPlugins folder next to Stride.GameStudio.exe:

   var akerPluginsDir = System.IO.Path.Combine(System.AppContext.BaseDirectory, "AkerMcpPlugins");
   if (System.IO.Directory.Exists(akerPluginsDir))
       foreach (var dll in System.IO.Directory.GetFiles(akerPluginsDir, "*.dll"))
           try { foreach (var t in System.Reflection.Assembly.LoadFrom(dll).GetTypes())
                     if (!t.IsAbstract && typeof(AssetsPlugin).IsAssignableFrom(t) && t.GetConstructor(System.Type.EmptyTypes) != null)
                         AssetsPlugin.RegisterPlugin(t); }
           catch { /* skip incompatible DLLs */ }
   

3. Build + deploy the adapter into Game Studio with setup-stride.ps1 (set -StrideBin to your Game Studio build output), then launch Game Studio and open a project + scene — the plugin starts the pipe server when a project opens.

Either way, the standalone MCP server then discovers the Stride engine automatically — same as Unity/Godot.

2. MCP Server Setup

1. Go to the latest GitHub Release.
2. Download the standalone server for your OS (AkerMcp.Server-win-x64.zip, -osx-x64.zip, or -linux-x64.zip).
3. Extract the archive anywhere on your computer.

Connecting an AI Client

Point your AI client to the standalone executable you extracted in Step 2.

Important: Make sure the Unity plugin is running (green status in the AkerMcp window) before using any tools from the AI client.

Claude Code (CLI)

claude mcp add game-engine -- /absolute/path/to/extracted/AkerMcp.Server

Claude Desktop / Cursor / Windsurf

Open the MCP settings (or claude_desktop_config.json) and add the server:

{
  "mcpServers": {
    "game-engine": {
      "command": "/absolute/path/to/extracted/AkerMcp.Server",
      "args": []
    }
  }
}

Windows users: Replace the command path with the full Windows path to the .exe, for example "C:\\Tools\\AkerMcp.Server\\AkerMcp.Server.exe". Remember to use double backslashes in JSON!

Google Antigravity

Antigravity reads mcp_config.json from its user-data directory (~/.gemini/antigravity/ or %USERPROFILE%\.gemini\antigravity\). Add:

{
  "mcpServers": {
    "game-engine": {
      "command": "C:/Tools/AkerMcp.Server/AkerMcp.Server.exe",
      "args": [],
      "type": "stdio"
    }
  }
}

VS Code + Copilot

Add to your .vscode/settings.json or use the MCP: Add Server command:

{
  "mcp": {
    "servers": {
      "game-engine": {
        "command": "C:\\Tools\\AkerMcp.Server\\AkerMcp.Server.exe",
        "args": []
      }
    }
  }
}

Alternative: Running from Source (For Developers)

If you cloned the repository or prefer running via the .NET SDK instead of using the standalone binaries, use dotnet run. This is often necessary if you are actively modifying the MCP server code.

CLI command:

claude mcp add game-engine -- dotnet run --project /absolute/path/to/AkerMCP/Server -c Release --verbosity quiet --nologo

JSON Configuration (for Claude Code config, Cursor, Antigravity, etc):

{
  "mcpServers": {
    "game-engine": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:/absolute/path/to/AkerMCP/Server",
        "-c",
        "Release",
        "--verbosity",
        "quiet",
        "--nologo"
      ]
    }
  }
}

Advanced: Building from Source (For Developers)

If you want to modify AkerMCP or test the included Unity project, you'll need the .NET 8.0+ SDK.

Step 1 — Clone and Build

git clone https://github.com/lorenzo-cambiaghi/AkerMCP.git
cd AkerMCP
dotnet build -c Release
dotnet publish Shared/AkerMcp.Shared.csproj -c Release -o .publish

Step 2 — Unity Plugin Setup

If you are modifying the source code and want to push changes to your own Unity project:

1. Copy this repo's plugins/unity folder into your own Unity project as Assets/AkerMcp.
2. Create Assets/AkerMcp/Plugins/ and copy all .dll files from .publish/ and Client/bin/Release/netstandard2.1/.
3. Copy the Unity Roslyn Compilers (Microsoft.CodeAnalysis.dll, etc.) from your Unity Editor installation (.../Editor/Data/MonoBleedingEdge/lib/mono/4.5/) into the Plugins/ folder.

If you just want to run the included sample, run ./setup-samples.sh (or setup-samples.bat on Windows) once to link the plugin into samples/unity, then ./copy-dlls.sh (or copy-dlls.bat) to build and copy all dependencies. Open samples/unity in Unity.

Packaging a Release

On Windows, .\publish-release.ps1 -Version v1.2.3 does the whole release in one command: builds the packages (Unity must be closed), tags the commit, creates the GitHub Release and uploads the five artifacts via the GitHub API (auth via GITHUB_TOKEN or the stored git credential). Use -DryRun to preview, -SkipBuild to reuse existing Build/ output.

The six release artifacts are: AkerMCP.unitypackage (Unity plugin), AkerMcp.Godot-addon.zip (Godot addon — extract into your project's addons/), AkerMcp.Stride-source.zip (Stride adapter source + install-stride-wrapper.ps1 — build it against your Game Studio per 1c. Stride Setup; it is not a prebuilt binary because it links your specific Stride editor assemblies), and the three standalone server builds (AkerMcp.Server-{win,osx,linux}-x64.zip).

Alternatively, run build-package.bat (Windows) or ./build-package.sh (Mac/Linux) to only produce the artifacts in the local Build/ folder (gitignored), then upload them as release assets manually. Binaries are distributed via Releases, not committed to the repository.

Verifying the Connection

Once both the Unity plugin and an AI client are running, you can verify the connection:

1. In Unity — the AkerMcp window should show Running (green)
2. In the AI client — ask the AI to use the inspect tool:

"Inspect the scene hierarchy"

You should get back a tree of objects with their components:

Player  [Transform, Rigidbody]
  PlayerCamera  [Transform, Camera]
Enemy_1  [Transform, MeshFilter, MeshRenderer, BoxCollider, Rigidbody]
Enemy_2  [Transform, MeshFilter, MeshRenderer, BoxCollider, Rigidbody]
Ground  [Transform, MeshFilter, MeshRenderer, MeshCollider]

If you see this, everything is working.

MCP Tools

Scene Manipulation

Development Workflow

Scene & 2D Authoring

Build a 2D prototype end-to-end — scene, placeholder art, and gameplay — without leaving the AI session.

Engine support: all three engines implement these. create_sprite imports + places a sprite on Unity and Godot; on Stride it persists a real .sdtex texture asset in the package (via the editor's SessionViewModel) and also adds a runtime preview entity for immediate visibility. new_scene/open_scene/save_scene work on Unity and Godot (file-on-disk scenes) and on Stride (package-managed SceneAsset via the editor). write_script works on all three. (Stride's create_sprite + scene creation are verified live in Game Studio.)

create_sprite shape-spec — drawn in order (painter's): ellipse, rect (with rx for rounded corners), polygon, line/polyline, and path (an SVG path-data subset). Each shape takes a fill (hex or linear gradient), optional stroke/strokeWidth, and opacity. Example (a flat bird placeholder):

{
  "name": "bird", "pixels_per_unit": 64, "pivot": {"x":0.5,"y":0.5},
  "scene_path": "/World", "position": {"x":-3,"y":0,"z":0},
  "spec": { "width":64, "height":64, "shapes": [
    {"type":"ellipse","cx":31,"cy":34,"rx":23,"ry":21,"fill":"#FFC107","stroke":"#C98A00","strokeWidth":2},
    {"type":"polygon","points":[[52,29],[64,33],[52,38]],"fill":"#FF8C00"} ] }
}

Keep placeholders flat and geometric — recognizable silhouette over detail. For arbitrary SVG (boolean paths, filters, tracing) a dedicated vector tool would be the right home; create_sprite deliberately targets the clean-prototype niche.

Platform & Build

Engine-neutral build pipeline control (backed by the optional IBuildManager; implemented for Unity, Godot and Stride).

Engine differences are handled gracefully: e.g. Godot and Stride have no global active target, so switch_build_target reports that and you pass the platform directly to build_player.

Visual Verification

list_windows / capture_window are OS-level and engine-independent: they work with no engine connected and can capture external apps (browsers, dashboards, other editors) — useful for debugging and cross-app workflows.

How take_screenshot works

The tool follows a hybrid capture strategy that prefers quality but always succeeds:

1. Engine-internal path (implemented by all three adapters) — captures the Scene view directly from the editor's render buffer including gizmos (Unity GrabPixels, Godot viewport, Stride editor back-buffer via Texture.Save). Works even when the editor window is occluded or partially off-screen. Highest quality.
2. OS-level fallback (automatic, cross-platform on Windows + macOS) — captures the engine's main window without stealing foreground focus. Works for any C# engine without requiring adapter code. Per-OS implementation is selected at runtime:
   • Windows — Win32 PrintWindow(PW_RENDERFULLCONTENT) via user32.dll
   • macOS — Quartz CGWindowListCreateImage via CoreGraphics.framework + ImageIO.framework. Window discovery: enumerates on-screen windows owned by the engine PID; among those, prefers any whose title contains the engine name (anywhere — matches both "Unity 6000…" and "… Godot Engine") and within that subset picks the largest by area. If no title contains the engine name, falls back to the largest PID-owned window
   • Linux — not implemented; the engine adapter must implement IScreenCapture

Output is automatically (cross-platform via ImageSharp):

• Resized to a maximum of 1920px on the longest side
• Re-encoded as JPEG (quality 85)

Typical output size: ~150-400 KB, comfortably under Claude API image limits (~5 MB).

Parameters:

{ "view": "game" }   // default — captures the Game View
{ "view": "scene" }  // captures the active Scene View with gizmos (Unity / Godot / Stride)

Example:

→ set_property {"object_path": "/Player", "property_path": "Light.color", "value": {"r":1,"g":0,"b":0,"a":1}}
← Property 'Light.color' set successfully on /Player

→ take_screenshot {"view": "scene"}
← [JPEG image, 1920×1080, 287 KB]   // AI now sees the red light

macOS: Screen Recording permission

On macOS 10.15+, capturing windows from another process requires Screen Recording permission for the binary running the AkerMcp server. This affects only the OS-level path (capture_window and the take_screenshot fallback) — the engine-internal IScreenCapture path (implemented by all three engine adapters) works without any permission grant.

First-time setup:

1. The first time the OS-level fallback is invoked, macOS shows a permission prompt for the binary running the server (typically dotnet).
2. If you miss the prompt or denied it, open: System Settings → Privacy & Security → Screen Recording
3. Add (or enable the toggle for) the binary running AkerMcp:
   • If you launch via dotnet run --project Server → the entry is dotnet (or dotnet [version])
   • If you ship a self-contained build → the entry is your published executable
4. Restart the server. macOS caches the denial decision until the process restarts — granting alone is not enough.

Verification:

# Trigger a screenshot from your AI client. If permission is missing, the tool returns:
#   "macOS denied the screen capture (CGWindowListCreateImage returned NULL)..."
# Follow the steps above and try again after restarting the server.

Why no permission is needed for Unity (and most engines): The Unity adapter implements IScreenCapture using its own Camera/SceneView render buffer. That happens entirely inside the Unity process, so macOS doesn't treat it as cross-process screen capture and no permission is required. Only when no adapter capture exists does AkerMcp fall back to the OS-level path that triggers the permission flow.

Dynamic Code Execution (execute)

The execute tool runs arbitrary C# code inside the live editor — Unity, Godot, or Stride — using Roslyn. This is the most powerful tool: it can do anything that engine's editor API allows, with no fixed tool surface.

What it enables:

• Procedural scene generation (spawn 100 objects in a grid, create terrain, etc.)
• Bulk property modifications across many objects
• Asset manipulation (create materials, import textures, modify prefabs)
• Complex queries that go beyond what query supports
• Editor automation (menu items, build pipeline, custom importers)
• Anything you can do in an editor script for that engine

Built-in globals available in your code (shown for the Unity adapter; the Godot and Stride adapters expose equivalent globals over their own Node / Entity types):

Imported namespaces (no using needed): System, System.Collections.Generic, System.Linq, plus the engine's namespaces — UnityEngine/UnityEditor (Unity), Godot (Godot), Stride.Engine/Stride.Core.Mathematics (Stride).

Need another namespace? Add using ...; directives at the top of the snippet — they are hoisted to file scope automatically (e.g. using System.IO;).

Examples (Unity-flavored; the same patterns apply with each engine's API):

// Create a grid of cubes
for (int x = 0; x < 5; x++)
    for (int z = 0; z < 5; z++) {
        var cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
        cube.name = $"Cube_{x}_{z}";
        cube.transform.position = new Vector3(x * 2, 0, z * 2);
    }

// Set all enemies to red
var enemies = FindAll<Renderer>()
    .Where(r => r.gameObject.name.StartsWith("Enemy"))
    .ToArray();
foreach (var r in enemies)
    r.material.color = Color.red;
return $"Colored {enemies.Length} enemies";

// Return scene stats
var objects = FindAll<GameObject>();
var types = objects
    .SelectMany(go => go.GetComponents<Component>())
    .Where(c => c != null)
    .GroupBy(c => c.GetType().Name)
    .Select(g => $"{g.Key}: {g.Count()}")
    .ToArray();
return string.Join("\n", types);

Note: Each execute call is compiled and run independently — variables do not persist between calls, so every script must be self-contained. The evaluator runs on Unity's main thread with full Editor API access; Debug.Log output produced during the run is captured and returned in the output field.

How property paths work

Properties are accessed via dot-notation paths resolved at runtime through reflection:

transform.position.x          → float
Rigidbody.mass                → float (targets a specific component)
MeshRenderer.material.color   → Color

When a property name is ambiguous (e.g. enabled exists on multiple components), prefix it with the component type: Rigidbody.enabled, MeshRenderer.enabled.

MCP Resources

Type System

The serializer converts between JSON and .NET types via reflection. It handles:

• Primitives — int, float, double, bool, string, enum
• Structs — any value type, constructed from JSON via field/property matching
• Arrays — T[] from JSON arrays
• Lists — List<T> from JSON arrays
• Dictionaries — Dictionary<string, T> from JSON objects
• Nested types — recursive resolution (e.g. Bounds containing Vector3 fields)
• Nullable — automatic unwrap

The Unity adapter registers optimized converters for:

Vector2  Vector3  Vector4  Vector2Int  Vector3Int
Quaternion  Color  Color32  Rect  RectInt
Bounds  BoundsInt  LayerMask

JSON examples:

{ "x": 1.0, "y": 2.0, "z": 3.0 }                                              // Vector3
{ "r": 0.5, "g": 0.0, "b": 1.0, "a": 1.0 }                                    // Color
{ "center": { "x": 0, "y": 0, "z": 0 }, "size": { "x": 10, "y": 10, "z": 10 }} // Bounds
[{ "x": 0, "y": 0, "z": 0 }, { "x": 1, "y": 1, "z": 1 }]                      // Vector3[]

Example Session

→ inspect {"target": "/Player"}
← {
    "typeName": "Rigidbody",
    "path": "/Player",
    "components": [
      {"name": "Transform", "enabled": true},
      {"name": "Rigidbody", "enabled": true}
    ],
    "properties": [
      {"name": "position", "type": "Vector3", "value": {"x":0,"y":1,"z":0}},
      {"name": "Rigidbody.mass", "type": "float", "value": 1.0},
      ...
    ],
    "childNames": ["PlayerCamera"]
  }

→ select {"object_path": "/Player/PlayerCamera"}
← {"selected": true, "path": "/Player/PlayerCamera", "name": "PlayerCamera",
    "components": [{"name":"Transform"}, {"name":"Camera"}]}

→ set_property {
    "object_path": "/Player",
    "property_path": "position",
    "value": {"x": 10, "y": 0, "z": 5}
  }
← Property 'position' set successfully on /Player

→ query {"type_filter": "Camera"}
← [{"path": "/Player/PlayerCamera", "type": "Camera", "name": "PlayerCamera"}]

→ refresh_scripts {}
← Recompilation requested. Status: idle
  Last compile: 14:32:05
  Result: SUCCESS
  No errors or warnings.

→ get_console_logs {"level_filter": "error", "count": 10}
← (No matching log entries)

Architecture

                  ┌──────────────────────┐
                  │  LLM (Claude, etc.)  │
                  └──────────┬───────────┘
                             │ JSON-RPC 2.0 / stdio
                  ┌──────────▼───────────┐
                  │    AkerMCP Server    │   .NET 8 console process
                  │   20+ MCP tools      │
                  │    5 MCP resources   │
                  └──────────┬───────────┘
                             │ Named Pipe + MessagePack
                  ┌──────────▼───────────┐
                  │   Engine Plugin      │   runs inside Unity / Godot / Stride / Flax
                  │   ISceneGraph impl   │
                  └──────────────────────┘

How it works

1. The engine plugin starts a named-pipe server and writes a lock file to the system temp directory.
2. The MCP server scans for lock files, connects to the pipe, and begins forwarding tool calls.
3. The LLM sends JSON-RPC requests over stdio. The server forwards them to the engine plugin via MessagePack IPC and returns results as JSON.
4. The engine plugin dispatches requests to the main thread, executes reflection-based operations through ISceneGraph/ISceneNode, and returns results.

Property paths like transform.position.x are resolved at runtime by PropertyPathResolver, which walks the object graph via cached reflection metadata. Struct value-type propagation is handled automatically.

Project structure

AkerMCP/
├── AkerMcp.sln
├── Shared/                              AkerMcp.Shared (netstandard2.1)
│   ├── Protocol/                        JSON-RPC and MCP message models
│   ├── Abstraction/                     Engine-agnostic interfaces
│   ├── Reflection/                      PropertyPathResolver, inspector, cache
│   ├── Serialization/                   GenericSerializer, TypeRegistry
│   └── Ipc/                             Named pipe channel, binary framing
├── Server/                              AkerMcp.Server (net8.0 console app)
│   ├── McpServer.cs                     JSON-RPC dispatcher, MCP lifecycle
│   ├── ToolRegistry.cs                  20+ generic tool definitions
│   ├── ResourceRegistry.cs              5 resource definitions
│   ├── EngineConnection.cs              IPC client to engine plugin
│   ├── StdioTransport.cs                stdin/stdout transport
│   ├── ImageProcessor.cs                Resize + JPEG normalization (cross-platform via ImageSharp)
│   ├── SpriteRasterizer.cs              shape-spec → RGBA PNG (pure-managed ImageSharp.Drawing) for create_sprite
│   └── Platform/                        OS-level window capture
│       ├── IPlatformScreenCapture.cs    Common interface
│       ├── PlatformScreenCapture.cs     Runtime OS-based factory
│       ├── Windows/
│       │   └── WindowsScreenCapture.cs  Win32 PrintWindow + GDI+
│       └── Mac/
│           └── MacScreenCapture.cs      Quartz CGWindowListCreateImage + ImageIO P/Invoke
├── Client/                              AkerMcp.Client (netstandard2.1)
│   ├── EnginePluginBase.cs             Abstract base for adapters
│   ├── IpcRequestHandler.cs            Request routing and execution
│   ├── PluginDiscovery.cs              Lock-file based auto-discovery
│   ├── MainThreadDispatcherBase.cs     Thread-safe queue with TCS pattern
│   └── ClientConfiguration.cs          Client-side settings
├── plugins/                            Canonical engine adapters (the shippable plugins)
│   ├── unity/                          Unity adapter (→ Assets/AkerMcp in-project)
│   │   ├── UnitySceneGraph.cs           Scene traversal and node creation
│   │   ├── UnitySceneNode.cs            Reflection wrapper for GameObjects
│   │   ├── UnityTypeRegistration.cs     MessagePack types and aliases
│   │   └── Editor/                      Editor-only tooling
│   │       ├── DynamicEvaluatorV2.cs    Roslyn-powered C# execution engine
│   │       ├── McpEditorWindow.cs       Unity Editor UI for MCP server
│   │       ├── UnityCompilationSupport.cs Script compilation tools
│   │       ├── UnityEditorContext.cs    Active selection and console logs
│   │       ├── UnityMainThreadDispatcher.cs Unity main thread marshalling
│   │       ├── UnityScreenCapture.cs    Game/Scene view render-buffer capture
│   │       └── UnityMcpPlugin.cs        Plugin entry point
│   ├── godot/                          Godot 4.x (.NET) adapter (→ addons/aker_mcp in-project)
│       ├── AkerMcpEditorPlugin.cs       [Tool] EditorPlugin entry + main-thread pump
│       ├── GodotMcpPlugin.cs            EnginePluginBase subclass
│       ├── GodotSceneGraph.cs           Edited-scene traversal and node creation
│       ├── GodotSceneNode.cs            Reflection wrapper for Nodes (no components)
│       ├── GodotCapabilities.cs         Type resolution and engine metadata
│       ├── GodotTypeRegistration.cs     Vector/Color/Rect2/Aabb converters
│       ├── GodotMainThreadDispatcher.cs Queue drained by EditorPlugin._Process
│       ├── GodotEditorContext.cs        Selection, scene I/O, log buffer
│       ├── GodotCompilationSupport.cs   `dotnet build` + MSBuild diagnostics
│       ├── GodotScreenCapture.cs        Editor viewport capture
│       └── GodotCodeExecutor.cs         Roslyn-powered C# execution engine
│   └── stride/                         Stride (Game Studio) adapter (.csproj + sources)
│       ├── StrideMcpPlugin.cs           AssetsPlugin entry (Game Studio hook)
│       ├── StrideBootstrap.cs           Idempotent Register() — shared by both loaders
│       ├── StrideEnginePlugin.cs        EnginePluginBase (composed; hosts the IPC server)
│       ├── StrideSceneGraph.cs          Live edited-scene traversal
│       ├── StrideSceneNode.cs           Reflection wrapper for Entities + components
│       ├── StrideSceneBridge.cs         Quantum writes (undo) + editor-game access
│       ├── StrideCapabilities.cs        Type resolution and engine metadata
│       ├── StrideMainThreadDispatcher.cs WPF Dispatcher marshalling
│       ├── StrideEditorContext.cs       Selection + GlobalLogger console capture
│       ├── StrideCompilationSupport.cs  `dotnet build` + MSBuild diagnostics
│       ├── StrideScreenCapture.cs       Scene-view back-buffer capture (Texture.Save)
│       ├── StrideBuildManager.cs        Platform/build (executable projects)
│       └── StrideCodeExecutor.cs        Roslyn-powered C# execution engine
│   ├── stride-startuphook/             DOTNET_STARTUP_HOOKS bootstrap (binary-install path)
│   │   └── StartupHook.cs               Registers the adapter once Game Studio loads
│   └── stride-launcher/                Per-launch wrapper (sets the hook for the GS child only)
│       └── Program.cs                   Starts ../Stride.GameStudio.exe with the hook injected
├── samples/                            Minimal harness projects (open in the editor)
│   ├── unity/                          Unity project; Assets/AkerMcp → junction to plugins/unity
│   └── godot/                          Godot project; addons/aker_mcp → junction to plugins/godot
└── setup-samples.bat / .sh             Recreates the sample junctions after a clone

The plugins under plugins/ are the canonical, shippable source. The samples/ projects are thin shells that link the plugin in via a directory junction (created by setup-samples), so there is a single copy of each adapter — the editor edits it in place. The junctions are gitignored; run setup-samples once after cloning.

Writing an Engine Adapter

To support a new engine (e.g. Godot, Stride, Flax), subclass EnginePluginBase and implement the required interfaces:

public class MyEnginePlugin : EnginePluginBase
{
    // Required
    protected override ISceneGraph CreateSceneGraph() => new MySceneGraph();
    protected override IEngineCapabilities CreateCapabilities() => new MyCapabilities();
    protected override IMainThreadDispatcher CreateDispatcher() => new MyDispatcher();

    // Optional
    protected override IEditorContext? CreateEditorContext() => new MyEditorContext();
    protected override IAssetManager? CreateAssetManager() => null;
    protected override ICompilationSupport? CreateCompilationSupport() => new MyCompilationSupport();
    protected override IScreenCapture? CreateScreenCapture() => new MyScreenCapture();
    protected override ISpriteImporter? CreateSpriteImporter() => new MySpriteImporter();
    protected override ISceneManager? CreateSceneManager() => new MySceneManager();

    protected override void Log(string message) { /* ... */ }
    protected override void LogError(string message) { /* ... */ }
}

Tip for the macOS OS-level fallback: IEngineCapabilities.EngineName is used as a window-title preference signal — the macOS capture path prefers PID-owned windows whose title contains this string (anywhere in the title) to disambiguate the editor's main window from inspector/floating panels. The match is case-insensitive and works for both prefix-style titles (Unity: "Unity 6000.x …") and suffix-style titles (Godot: "Scene - Project - Godot Engine"). If no window matches, the largest PID-owned window is used as a fallback, so even a non-matching EngineName won't break the capture.

Register custom type converters for engine-specific structs:

TypeRegistry.Instance.RegisterCustomSerializer<Vector3>(
    v => new Dictionary<string, object?> { ["x"] = v.x, ["y"] = v.y, ["z"] = v.z },
    d => new Vector3(F(d, "x"), F(d, "y"), F(d, "z"))
);

AI Integration Rules

AkerMCP embeds comprehensive usage instructions directly into each tool's description served via the MCP protocol. This means any AI client (Claude, Cursor, Copilot, Antigravity) automatically learns how to use all the tools correctly — including property path syntax, the Inspect → Modify → Verify workflow, Roslyn execution globals, compilation verification, and visual verification via screenshots — with zero configuration.

Optional: Boost with a rules file

For even better results, you can add a rules file to your project root. This reinforces the built-in instructions and gives the AI additional context about common workflows and anti-patterns.

Recommended: Use AGENTS.md in your project root. It's the most widely supported convention.

Rules template

Copy everything inside the block below into your rules file:

<agent_instructions>

#### AkerMCP — AI Integration Rules

You have access to a C# game engine — **Unity, Godot, or Stride** (all equally supported) — via the `game-engine` MCP server. This gives you 20+ tools to inspect, query, modify, script, and visually verify the active scene, plus platform/build control — all from the editor. The `execute` tool runs arbitrary C# (Roslyn) against the live editor, so there is effectively no limit to what you can do.

#### Available Tools (quick reference)

| Tool | Use when... |
|------|-------------|
| `inspect` | You need to see what's on an object — components, properties, children |
| `get_property` | You know the exact path and want a single value |
| `set_property` | You want to change one property with undo support |
| `call_method` | You need to invoke a method (e.g. `SetActive`, `AddForce`) |
| `query` | You need to find objects by type, name pattern, or tag |
| `create` | You need to add a new object to the scene |
| `delete` | You need to remove an object (destructive, has undo) |
| `select` | You want to highlight an object in Unity's Hierarchy/Inspector |
| `get_selection` | You want to know what the user currently has selected |
| `refresh_scripts` | You just wrote or modified a `.cs` file and need to trigger recompilation |
| `get_compile_errors` | You need to check if scripts compiled successfully |
| `get_console_logs` | You need to read runtime errors, warnings, or debug output |
| `execute` | You need to run arbitrary C# code (procedural generation, bulk ops, complex logic) |
| `take_screenshot` | You need to **see** the result of a change (placement, materials, lighting, UI) |
| `list_platforms` / `get_platform_settings` / `set_platform_settings` | You need to inspect or change build/player settings for a platform |
| `switch_build_target` / `build_player` | You need to switch the active platform or produce a build (APK/exe/…) |
| `list_windows` / `capture_window` | You need to screenshot any OS window (incl. external apps), not just the engine |

#### Core Workflow: Inspect → Modify → Verify

Always follow this pattern:

1. **Inspect first.** Before modifying anything, call `inspect` to see the object's components, properties, and current values. Never guess.
2. **Modify.** Use `set_property` for single changes, `execute` for complex operations.
3. **Verify.** Call `get_property` or `inspect` again to confirm the change took effect. Check `get_console_logs` if something seems wrong.
4. **Visually verify (when relevant).** For changes that affect what the user *sees* — placement, materials, lighting, UI layout, scale — call `take_screenshot` after the change to confirm the result looks right. This catches problems that property values alone cannot reveal (e.g. an object placed inside another, a material that compiled but renders pink, a UI element clipped off-screen).

#### Property Path Syntax

Properties use **dot-notation** resolved via reflection:

**Rules:**
- Transform properties (`position`, `rotation`, `localScale`, `eulerAngles`) don't need a prefix
- Other components need the type prefix: `Rigidbody.mass`, `Camera.fieldOfView`, `Light.intensity`
- Nested properties work: `MeshRenderer.material.color.r`
- Array indexing works: `mesh.vertices[0]`

**Structs are passed as JSON objects:**
```json
{"x": 1.0, "y": 2.0, "z": 3.0}           // Vector3
{"r": 1.0, "g": 0.0, "b": 0.0, "a": 1.0} // Color

selectedObject              // Currently selected object (or null)
Find("Player")              // find by name
FindAll<Rigidbody>()        // find all components/nodes of a type
Create("MyObject")          // create an empty object
Log("message")              // log to the engine console

// Wrong — 'player' from a previous call no longer exists
return player.transform.position;

// Right — re-acquire what you need within the same script
var player = Find("Player");
return player.transform.position;

// Good — returns useful info
var count = FindAll<Rigidbody>().Length;
return $"Found {count} rigidbodies";

// Bad — no feedback
FindAll<Rigidbody>();  // returns null, you won't know the result

{ "view": "game" }   // default — Game View, what the player sees
{ "view": "scene" }  // Scene View, useful for inspecting the full editor with gizmos

→ execute "for (int i = 0; i < 50; i++) { var t = GameObject.CreatePrimitive(PrimitiveType.Cube); t.transform.position = new Vector3(Random.Range(-20,20), 0, Random.Range(-20,20)); t.name = $\"Tree_{i}\"; } return \"spawned 50\";"
← spawned 50

→ take_screenshot {"view": "scene"}
← [JPEG image]
   ← AI sees: cubes are clustered too tightly in one corner — distribution looks wrong
   → Fixes the script and re-runs.

→ refresh_scripts {}
← Recompilation requested. Result: FAILED
  === ERRORS (1) ===
  Assets/Scripts/Player.cs(15,9): error CS1002: ; expected

→ (fix the file)

→ refresh_scripts {}
← Result: SUCCESS. No errors or warnings.

/Player
/Player/PlayerCamera
/Environment/Trees/Oak_01

Troubleshooting

The server says "No engine plugin discovered"

The Unity plugin must be started before the MCP server. Open Window → AkerMcp in Unity and click Start first.

Unity shows DLL loading errors

Make sure you copied all DLLs from the .publish/ folder, including System.Text.Json.dll. Unity does not ship this library by default.

Property not found on component

Prefix the property with the component type name: Rigidbody.mass instead of just mass. This disambiguates when multiple components share property names.

The first server start is slow

dotnet run compiles the server on first launch. Subsequent starts are fast. You can also use dotnet build -c Release ahead of time, then run the compiled binary directly:

./Server/bin/Release/net8.0/AkerMcp.Server

Connection drops after Unity recompiles scripts

Domain reload in Unity tears down the plugin to safely release file locks. Re-click Start in the AkerMcp window after a recompile. The MCP server features an infinite background retry loop and will automatically detect the new instance and reconnect—you do not need to restart the server.

macOS: take_screenshot returns "macOS denied the screen capture"

Only happens when the OS-level fallback is used (engine adapter doesn't implement IScreenCapture). Open System Settings → Privacy & Security → Screen Recording, enable the entry for the binary running the server (typically dotnet), then restart the server — macOS caches the denial decision until the process restarts. See macOS: Screen Recording permission for the full procedure.

macOS: take_screenshot returns "No on-screen window found for PID"

Only happens with the OS-level fallback. The engine's main window cannot be located via title prefix. Verify that IEngineCapabilities.EngineName in your adapter matches the actual editor window title prefix (e.g. "Unity" for Unity Editor). The match is case-insensitive but must be a prefix.

Unity says "Opening file failed: Access is denied"

If you downloaded the repository as a ZIP or cloned it on Windows, Unity might complain about .asset or .meta files being read-only. To fix this:

1. Right-click the samples\unity folder in Windows Explorer.
2. Go to Properties.
3. Uncheck the Read-only box and click Apply (apply to all folders, subfolders, and files). Alternatively, open Command Prompt and run: attrib -R "samples\unity\*.*" /S /D

License

Apache 2.0