Skip to main content
Glama
Sign In
game-mcp

game-mcp

by lauripiispanen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Game MCP Server

A thin MCP (Model Context Protocol) server that bridges AI assistants to running game instances for testing, debugging, and verification.

Overview

This server acts as a proxy between Claude (or any MCP-compatible AI) and your game. It:

  • Launches your game process if not already running

  • Maintains a TCP connection for bidirectional communication

  • Forwards commands from the AI to your game

  • Returns responses, including screenshots, back to the AI

Engine-agnostic: Works with any game engine (Godot, Unity, Unreal, custom) as long as your game implements the simple TCP protocol.

Related MCP server: openrct2-mcp

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         AI Assistant (Claude)                        │
└─────────────────────────────────────┬───────────────────────────────┘
                                      │ MCP Protocol (stdio)
                                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Game MCP Server                              │
│                                                                      │
│  - Launches game process if needed                                   │
│  - TCP connection to game (default port 6789)                        │
│  - Forwards commands, returns responses                              │
│  - Handles screenshots as MCP ImageContent                           │
└─────────────────────────────────────┬───────────────────────────────┘
                                      │ TCP + JSON (newline-delimited)
                                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Your Game (with DevServer)                        │
│                                                                      │
│  - Listens on TCP port                                               │
│  - Executes commands, returns results                                │
│  - You implement the command handlers                                │
└─────────────────────────────────────────────────────────────────────┘

Installation

bun install

Configuration

Configure via environment variables:

Variable

Default

Description

GAME_PROJECT_PATH

(none)

Path to your game/project directory

GAME_PORT

6789

TCP port for game communication

GODOT_PATH

godot

Command to launch your game

CONNECT_TIMEOUT_MS

5000

Connection timeout

COMMAND_TIMEOUT_MS

10000

Command response timeout

Claude Code Integration

Add to your Claude Code MCP config (~/.config/claude-code/settings.json):

{
  "mcpServers": {
    "game": {
      "command": "bun",
      "args": ["run", "/path/to/game-mcp/src/index.ts"],
      "env": {
        "GAME_PROJECT_PATH": "/path/to/your/game",
        "GODOT_PATH": "godot"
      }
    }
  }
}

For non-Godot engines, set GODOT_PATH to whatever command launches your game.

MCP Tools

game_connect

Connects to the game, launching it if necessary.

Parameters:

  • project_path (string, optional): Override the game project path

  • restart (boolean, optional): Kill and relaunch the game

  • port (integer, optional): TCP port (default: 6789)

  • timeout_ms (integer, optional): Connection timeout

Returns: List of available commands from the game.

game_command

Sends a command to the game.

Parameters:

  • command (string, required): Command name

  • args (object, optional): Command arguments

  • timeout_ms (integer, optional): Response timeout

Returns: Command result, potentially including image data.

Game-Side Protocol

Your game needs to implement a TCP server that:

  1. Listens on the configured port (default 6789)

  2. Accepts newline-delimited JSON messages

  3. Responds with newline-delimited JSON

Request Format

{"id": "uuid", "command": "command_name", "args": {"key": "value"}}

Response Format

{"id": "uuid", "success": true, "data": {...}}

With image:

{"id": "uuid", "success": true, "data": {}, "image": "base64-encoded-png"}

Error:

{"id": "uuid", "success": false, "error": "Error message"}

Required Command: list_commands

Your game should implement list_commands to tell the AI what's available:

// Request
{"id": "1", "command": "list_commands", "args": {}}

// Response
{
  "id": "1",
  "success": true,
  "data": {
    "commands": [
      {
        "name": "screenshot",
        "description": "Capture the game viewport",
        "args": {
          "scale": {"type": "number", "optional": true}
        }
      },
      {
        "name": "get_player_state",
        "description": "Get player position and health",
        "args": {}
      }
    ]
  }
}

Example Commands

Common commands you might implement in your game:

Command

Description

screenshot

Capture viewport as PNG

player_state

Get player position, health, etc.

teleport

Move player to coordinates

spawn

Spawn entities for testing

get_errors

Retrieve recent error logs

performance

Get FPS and performance metrics

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers