AkerMCP

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

| Capability | Unity | Godot | Stride | |---|:--:|:--:|:--:| | Inspect · query · get/set property (incl. nested) | ✅ | ✅ | ✅ | | call_method · create · delete (native Undo) | ✅ | ✅ | ✅ | | execute — arbitrary C# via Roslyn | ✅ | ✅ | ✅ | | Selection · console logs · recompile/compile-errors | ✅ | ✅ | ✅ | | Scene-view screenshot with editor gizmos | ✅ | ✅ | ✅ | | Platform/build tools (list · switch · build_player) | ✅ | ✅ | ✅ | | 2D vector placeholders (create_sprite, server-rasterized) | ✅ | ✅ | ✅ | | Scene management (new_scene · open_scene · save_scene) | ✅ | ✅ | ✅ |

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 

*(Curious about the internal technical details? Jump to the [Architecture](#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)"

→ setproperty {"objectpath": "/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**](https://github.com/lorenzo-cambiaghi/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](#the-perfect-combo-akermcp--lynxmcp)
- [Quick Start (Recommended)](#quick-start-recommended)
- [Connecting an AI Client](#connecting-an-ai-client)
  - [Claude Code (CLI)](#claude-code-cli)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf)
  - [Google Antigravity](#google-antigravity)
  - [VS Code + Copilot](#vs-code--copilot)
- [Advanced: Building from Source (For Developers)](#advanced-building-from-source-for-developers)
- [Verifying the Connection](#verifying-the-connection)
- [MCP Tools](#mcp-tools)
- [MCP Resources](#mcp-resources)
- [Type System](#type-system)
- [Example Session](#example-session)
- [Architecture](#architecture)
- [Writing an Engine Adapter](#writing-an-engine-adapter)
- [AI Integration Rules](#ai-integration-rules)
- [Troubleshooting](#troubleshooting)
- [License](#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](https://github.com/lorenzo-cambiaghi/AkerMCP/releases/latest) 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](https://github.com/lorenzo-cambiaghi/AkerMCP/releases/latest) 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):
   ```xml
   
   
   
   ```
   Make sure your project has `true` (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 ed

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lorenzo-cambiaghi](https://github.com/lorenzo-cambiaghi)
- **Source:** [lorenzo-cambiaghi/AkerMCP](https://github.com/lorenzo-cambiaghi/AkerMCP)
- **License:** Apache-2.0
- **Homepage:** https://github.com/lorenzo-cambiaghi/AkerMCP

Install and usage instructions live in the source repository linked above.