Ach MCP

An in-editor MCP (Model Context Protocol) server that exposes Unity convenience tools to AI assistants such as Claude. The server runs entirely inside the Unity Editor in C# (no separate process, no external bridge) and speaks MCP over HTTP.

Tools

Requirements

• Unity 2021.3+

• com.unity.nuget.newtonsoft-json (declared as a package dependency, installed automatically)

Installation

Add the package to your project's Packages/manifest.json:

{
  "dependencies": {
    "com.achieveone.ach-mcp": "https://github.com/achieveonepark/ach-mcp.git"
  }
}

Or use Window ▸ Package Manager ▸ + ▸ Add package from git URL and paste the repository URL.

Usage

1. Open Tools ▸ Ach MCP ▸ Control Panel.

2. Set a Port (default 8790) and click Start. Enable Auto-start on load to have it come up with the editor.

3. In the AI Client Setup section, click Configure next to a client (or Configure Detected to do all installed ones at once). Restart the client.

Once connected, ask the assistant to call the tools, e.g. "check the Unity console for errors", "show me the scene hierarchy", or "take a screenshot of the game view."

One-click client setup

The control panel writes this server into each client's config file, resolving the correct location for macOS / Windows / Linux automatically. Existing configs are merged (your other servers are preserved) and backed up once as *.ach-mcp.bak before the first change.

Clients that don't support HTTP MCP directly are bridged through mcp-remote, invoked as npx -y mcp-remote <url>. Those rows are marked "mcp-remote" and require Node.js (npx) on your PATH.

Manual configuration

If you'd rather edit config by hand, the server is a standard Streamable-HTTP MCP endpoint:

http://127.0.0.1:8790/mcp

Native-HTTP client (Claude Code, Cursor, …):

{ "mcpServers": { "ach-unity": { "type": "http", "url": "http://127.0.0.1:8790/mcp" } } }

stdio-only client (Claude Desktop, Codex):

{ "mcpServers": { "ach-unity": { "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:8790/mcp"] } } }

How it works

• Transport — a loopback HttpListener (127.0.0.1, so no admin/urlacl is needed) accepts JSON-RPC 2.0 POSTs at /mcp and returns a single JSON response (Streamable HTTP).

• Threading — HTTP requests are served on background threads; every tool marshals its Unity API calls onto the main thread via MainThreadDispatcher.

• Lifecycle — McpServerManager stops the listener before every domain reload and on editor quit, so the port is always released.

Adding your own tool

1. Implement IMcpTool in Editor/Tools/.

2. Declare Name, Description, and an InputSchema (JSON Schema).

3. Register it in ToolRegistry's static constructor.

internal sealed class MyTool : IMcpTool
{
    public string Name => "my_tool";
    public string Description => "What it does.";
    public JObject InputSchema => new JObject { ["type"] = "object" };

    public ToolResult Execute(JObject arguments)
    {
        var value = MainThreadDispatcher.Run(() => /* Unity API here */ 42);
        return ToolResult.Ok("Result: " + value);
    }
}