<div align="center" width="100%">

  <h1>✨ AI Game Developer — <i>GameDev MCP Server</i></h1>

[![NuGet](https://img.shields.io/nuget/v/com.IvanMurzak.GameDev.MCP.Server?label=NuGet&labelColor=333A41)](https://www.nuget.org/packages/com.IvanMurzak.GameDev.MCP.Server/)
[![MCP](https://badge.mcpx.dev 'MCP Server')](https://modelcontextprotocol.io/introduction)
[![Unreal](https://img.shields.io/badge/Unreal-Engine-0E1128?style=flat&logo=unrealengine&logoColor=white&labelColor=333A41 'Unreal-MCP plugin')](https://github.com/IvanMurzak/Unreal-MCP)
[![Unity](https://img.shields.io/badge/Unity-Engine-000000?style=flat&logo=unity&logoColor=white&labelColor=333A41 'Unity-MCP plugin')](https://github.com/IvanMurzak/Unity-MCP)
[![Godot](https://img.shields.io/badge/Godot-Engine-478CBF?style=flat&logo=godotengine&logoColor=white&labelColor=333A41 'Godot-MCP plugin')](https://github.com/IvanMurzak/Godot-MCP)</br>
[![Discord](https://img.shields.io/badge/Discord-Join-7289da?logo=discord&logoColor=white&labelColor=333A41 'Join')](https://discord.gg/cfbdMZX99G)
[![Stars](https://img.shields.io/github/stars/IvanMurzak/GameDev-MCP-Server 'Stars')](https://github.com/IvanMurzak/GameDev-MCP-Server/stargazers)
[![License](https://img.shields.io/github/license/IvanMurzak/GameDev-MCP-Server?label=License&labelColor=333A41)](https://github.com/IvanMurzak/GameDev-MCP-Server/blob/main/LICENSE)
[![Docker Image](https://img.shields.io/docker/image-size/aigamedeveloper/mcp-server/latest?label=Docker%20Image&logo=docker&logoColor=white&labelColor=333A41 'Docker Image')](https://hub.docker.com/r/aigamedeveloper/mcp-server)
[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)

  <img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/ai-developer-banner.jpg" alt="AI Game Developer" title="AI Game Developer" width="100%">

  <p>
    <a href="https://claude.ai/download"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/claude-64.png" alt="Claude" title="Claude" height="36"></a>&nbsp;&nbsp;
    <a href="https://openai.com/index/introducing-codex/"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/codex-64.png" alt="Codex" title="Codex" height="36"></a>&nbsp;&nbsp;
    <a href="https://www.cursor.com/"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/cursor-64.png" alt="Cursor" title="Cursor" height="36"></a>&nbsp;&nbsp;
    <a href="https://code.visualstudio.com/docs/copilot/overview"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/github-copilot-64.png" alt="GitHub Copilot" title="GitHub Copilot" height="36"></a>&nbsp;&nbsp;
    <a href="https://gemini.google.com/"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/gemini-64.png" alt="Gemini" title="Gemini" height="36"></a>&nbsp;&nbsp;
    <a href="https://antigravity.google/"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/antigravity-64.png" alt="Antigravity" title="Antigravity" height="36"></a>&nbsp;&nbsp;
    <a href="https://code.visualstudio.com/"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/vs-code-64.png" alt="VS Code" title="VS Code" height="36"></a>&nbsp;&nbsp;
    <a href="https://www.jetbrains.com/rider/"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/rider-64.png" alt="Rider" title="Rider" height="36"></a>&nbsp;&nbsp;
    <a href="https://visualstudio.microsoft.com/"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/visual-studio-64.png" alt="Visual Studio" title="Visual Studio" height="36"></a>&nbsp;&nbsp;
    <a href="https://github.com/anthropics/claude-code"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/open-code-64.png" alt="Open Code" title="Open Code" height="36"></a>&nbsp;&nbsp;
    <a href="https://github.com/cline/cline"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/cline-64.png" alt="Cline" title="Cline" height="36"></a>&nbsp;&nbsp;
    <a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/mcp-clients/kilo-code-64.png" alt="Kilo Code" title="Kilo Code" height="36"></a>
  </p>

</div>

Engine-agnostic [Model Context Protocol](https://modelcontextprotocol.io/) server shared by the game-engine MCP plugins:

- [Unity-MCP](https://github.com/IvanMurzak/Unity-MCP) — Unity Editor & games
- [Godot-MCP](https://github.com/IvanMurzak/Godot-MCP) — Godot Editor & games
- [Unreal-MCP](https://github.com/IvanMurzak/Unreal-MCP) — Unreal Editor & games

<div align="center" width="100%">

  <img src="https://github.com/IvanMurzak/GameDev-MCP-Server/raw/main/docs/img/docker-launch.gif" alt="Launching gamedev-mcp-server in Docker" title="Launching gamedev-mcp-server in Docker" width="100%">

</div>

It is a thin host over the NuGet packages [`com.IvanMurzak.McpPlugin.Server`](https://www.nuget.org/packages/com.IvanMurzak.McpPlugin.Server) and [`com.IvanMurzak.ReflectorNet`](https://www.nuget.org/packages/com.IvanMurzak.ReflectorNet), where all the real server logic lives. The server bridges MCP clients (Claude, Cursor, Copilot, …) and an engine plugin over SignalR:

```
MCP client  ⇄  gamedev-mcp-server  ⇄ (SignalR) ⇄  engine plugin (Unity / Godot / Unreal)
```

There is **no engine-specific code** in this repository — one server binary serves all three engine plugins. Tools, resources and prompts are provided dynamically by whichever engine plugin connects.

> **Not to be confused with** [AI-Game-Dev-Server](https://ai-game.dev) — the cloud LLM/billing proxy. This project is the **local** MCP stdio/http proxy host.

## Install / Run

### Pre-built executables

Download the zip for your platform from [Releases](https://github.com/IvanMurzak/GameDev-MCP-Server/releases) (`gamedev-mcp-server-<rid>.zip` — `win-x64`, `win-x86`, `win-arm64`, `linux-x64`, `linux-arm64`, `osx-x64`, `osx-arm64`), unzip, and run:

```bash
./gamedev-mcp-server --port 8080 --client-transport stdio
```

Typical MCP client configuration (stdio):

```json
{
  "mcpServers": {
    "GameDev-MCP": {
      "command": "path/to/gamedev-mcp-server",
      "args": ["--port=8080", "--client-transport=stdio"]
    }
  }
}
```

### Docker

```bash
docker run -i --rm -p 8080:8080 aigamedeveloper/mcp-server
```

### dotnet tool

```bash
dotnet tool install --global com.IvanMurzak.GameDev.MCP.Server
gamedev-mcp-server --port 8080
```

### Build from source

```bash
dotnet build com.IvanMurzak.GameDev.MCP.Server.csproj
dotnet run --project com.IvanMurzak.GameDev.MCP.Server.csproj -- --client-transport stdio --port 8080
```

Cross-platform self-contained executables for all 7 RIDs: `./build/build-all.sh` (bash) or `./build/build-all.ps1` (PowerShell). Outputs land in `publish/<rid>/` and are zipped as `gamedev-mcp-server-<rid>.zip` (skip zipping with `--no-zip` / `-NoZip`).

## Configuration

CLI arguments override environment variables.

| Environment variable | CLI argument | Default | Description |
| --- | --- | --- | --- |
| `MCP_PLUGIN_PORT` | `--port` | `8080` | Client → Server ← Plugin connection port |
| `MCP_PLUGIN_CLIENT_TIMEOUT` | `--plugin-timeout` | `10000` | Plugin → Server connection timeout (ms) |
| `MCP_PLUGIN_CLIENT_TRANSPORT` | `--client-transport` | `stdio` | Client → Server transport: `stdio` or `streamableHttp` |
| `MCP_PLUGIN_IDLE_TIMEOUT_SECONDS` | `--idle-timeout-seconds` | `28800` | streamableHttp idle-session eviction window (this host seeds 8h instead of the package default of 600s, so a local session survives a working day). Multi-tenant hosts should lower it and use a Redis session-migration record for long-window resumption |
| `MCP_AUTH` | `--auth` | transport-dependent (see [Authentication](#authentication)) | Authentication mode: `none` or `oauth` |
| `MCP_AUTH_ISSUER` | `--auth-issuer` | — | OAuth authorization-server URL (e.g. `https://ai-game.dev`). Required for `oauth` |
| `MCP_PUBLIC_URL` | `--public-url` | — | This server's canonical public URL / token audience (e.g. `https://ai-game.dev/mcp`). Required for `oauth`; seeds the Origin allow-list |
| `MCP_BIND` | `--bind` | `loopback` | Bind address: `loopback`, `any` (0.0.0.0), or a specific IP. Hosted deploys behind a proxy set `any`/`0.0.0.0` |
| `MCP_ALLOWED_ORIGINS` | `--allowed-origins` | — | Comma/semicolon-separated additional allowed browser Origins (added to loopback + the `--public-url` origin) |
| `MCP_LOG_LEVEL` | — | `Info` | Log verbosity floor: `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`. Read by NLog, so unlike the rest of this table it has no CLI equivalent |

Logs are written to `logs/server-log.txt` (and `logs/server-log-error.txt`); in stdio mode console logging is redirected to stderr so stdout stays clean for the MCP JSON stream.

The default level is `Info`. Set `MCP_LOG_LEVEL=Trace` to dump every MCP message
body while debugging a protocol issue — but expect volume: on a busy hosted
deployment Trace measured 39-54k lines/min (5-12 GB/day), which rotates
`server-log.txt` (10 MB x 5 archives) down to roughly ten minutes of retained
history. Lower verbosity keeps *more* usable history, not less.

## Authentication

The server is an OAuth 2.1 **resource server**. Two modes:

| Mode | Auth | Default for | Use |
| --- | --- | --- | --- |
| `none` | none — single-instance, zero-config | **stdio** | offline / local dev / CI |
| `oauth` | ES256 JWT validated locally via cached JWKS (with PAT introspection fallback); `401` + `resource_metadata` challenge | **streamableHttp** | signed-in localhost **and** hosted |

- **Transport-conditional default:** `stdio` defaults to `none`. `streamableHttp` defaults to `oauth` **when both `--auth-issuer` and `--public-url` are configured**; otherwise it stays on `none` and logs a warning (so the zero-config `docker run` / `--port 8080` quickstart still works). An explicit `--auth` always wins.
- **`oauth` requires** `--auth-issuer` (the authorization server, e.g. `https://ai-game.dev`) **and** `--public-url` (this server's canonical audience). Startup fails fast if either is missing while `--auth oauth` is set.
- **Origin validation** (DNS-rebinding defense) runs in **all** modes: a request with a non-allowed `Origin` gets `403`. Loopback and the `--public-url` origin are allowed by default; add more with `MCP_ALLOWED_ORIGINS`.
- **Bind** defaults to loopback. Set `--bind any` (or `0.0.0.0`) for a hosted deployment a reverse proxy must reach.

```bash
# Local, offline (stdio, none) — unchanged zero-config default:
gamedev-mcp-server --client-transport stdio --port 8080

# Hosted resource server (streamableHttp, oauth), reachable by nginx:
gamedev-mcp-server --client-transport streamableHttp --port 8080 \
  --auth oauth --auth-issuer https://ai-game.dev --public-url https://ai-game.dev/mcp \
  --bind 0.0.0.0
```

## Configure an AI agent

Write a project-scoped, pinned MCP client config for any supported AI agent from the terminal — no editor UI, no token copy/paste (native OAuth authorize):

```bash
# Local server, current project:
gamedev-mcp-server configure --agent claude-code
# Hosted server:
gamedev-mcp-server configure --agent codex --url https://ai-game.dev/mcp
# List agents:
gamedev-mcp-server configure --help
```

Each written config is **URL-only** (credentials are never written into project files) and carries the project pin (`…/p/<pin>` path segment) plus, for local servers, the deterministic per-project port — so agent sessions launched in this project folder route strictly to this project's engine. `--agent <id>` accepts any id from `configure --help` (e.g. `claude-code`, `codex`, `cursor`, `vscode-copilot`, …); `--transport stdio` writes a stdio spawn config instead of an HTTP one; `--project <path>` targets a different project root (default: current directory).

## Compatibility

| GameDev-MCP-Server | McpPlugin.Server | ReflectorNet | Engine plugins |
| --- | --- | --- | --- |
| **9.2.6** (current) | 8.2.0 | 5.4.0 | engine plugins on McpPlugin **8.x** |
| 9.2.4 (last 7.x) | 7.5.2 | 5.4.0 | engine plugins on McpPlugin **7.x** |
| 8.0.3 (legacy) | 6.11.0 | 5.3.1 | engine plugins on McpPlugin **6.x** |

Server releases `9.2.5` and newer build against McpPlugin **8.x**; `9.0.0`–`9.2.4` build against McpPlugin **7.x** (the instance-metadata handshake + `oauth` mode), and McpPlugin 6.x plugins pair with the `8.0.3` line.

For the exact pins of an intermediate version, see its entry on [Releases](https://github.com/IvanMurzak/GameDev-MCP-Server/releases) — this table tracks the current release and the last release on each earlier McpPlugin major rather than every patch, so it does not go stale between them.

## License

[Apache-2.0](LICENSE) — Copyright (c) 2026 Ivan Murzak