GameMaker MCP Server

A project-aware local MCP server for GameMaker Studio. It gives an MCP client structured access to a .yyp project: inspection, static analysis, guarded editing, object/room/shader operations, snapshots, validation, and official Igor builds.

The server uses the stable @modelcontextprotocol/sdk v1 line over stdio. It does not bind a network port. File operations stay inside one configured project, and existing text files use SHA-256 optimistic concurrency plus backups.

Highlights

• 165 MCP tools, 25 reusable workflow prompts, and 6 project resources;
• zero-config workspace auto-detection (open any GameMaker project folder in your AI client);
• CLI installer & manager (gamemaker-mcp install, doctor, connect) supporting 20 AI clients & IDEs (Amp, Antigravity, Claude, Cline, Codex, Copilot, Cursor, Factory, Gemini CLI, Goose, Grok, Junie, Kiro, LM Studio, opencode, Qodo, Qwen, VS Code, Warp, Windsurf);
• tolerant parsing of GameMaker .yyp/.yy JSON-like files, including trailing commas;
• project, asset, room, object-event, object-inheritance, sprite, sound, sequence, font, tileset, animation curve, timeline, included data files, audio/texture groups, and shader inspection;
• GML symbol/complexity diagnostics, FPS profiler, i18n scanner, draw state auditor, health score (0-100%), object hierarchy tree, doc exporter, state machine visualizer, dead GML code detector, global variable scanner, physics auditor, asset cross-referencer, and duplicate code finder;
• preflight GML syntax validator (gm_gml_validate_snippet), Igor diagnostic compiler (gm_project_compile_errors), GML Unit Test suite runner (gm_test_runner_run), and Feather JSDoc generator (gm_gml_docgen);
• exact GML patch previews and guarded writes;
• GameMaker folder, object, script, shader, object-event, timeline, test suite, data file, font configuration, tileset configuration, room-setting, room layer, room instance transform, and room-creation-code operations;
• integrity-checked project snapshots and guarded restoration;
• GML Finite State Machine, Particle System, GUI layout, and Inventory system boilerplate generators, plus a GML Unit Testing Framework scaffold;
• synchronous compile/run plus persistent background Igor Compile/PackageZip jobs, status, wait, and cancellation;
• automatic GameMaker runtime and Igor.exe discovery;
• project-root path sandbox, symlink/junction checks, per-file limits, read-only mode, and build opt-in.

Requirements

• Node.js 20 or newer;
• a GameMaker .yyp project;
• GameMaker Studio only for compile/package tools. Inspection and editing work without it.

Installation & Setup Guide

Method 1: Zero-Config Workspace Auto-Detect (Recommended)

Connect gamemaker-mcp once globally for all your AI clients:

npx gamemaker-mcp@latest connect all

How it works: Open any GameMaker project folder in any of the 20 supported AI clients (Claude Desktop, Google Antigravity, Cursor, VS Code, Windsurf, GitHub Copilot, Codex, Cline, etc.). The server automatically discovers and connects to your .yyp project file in the workspace directory dynamically at runtime without requiring a server restart!

---

Method 2: Automatic One-Line Setup with Explicit Project Path

Run the automated installer via npx, passing the path to your GameMaker .yyp project file or directory:

npx gamemaker-mcp@latest install "C:\Path\To\YourGame\YourGame.yyp"

What this command does automatically:

1. Verifies Node.js version (requires Node 20+).
2. Auto-detects installed GameMaker Studio runtimes & Igor.exe.
3. Validates your GameMaker .yyp project structure.
4. Generates a local mcp-config.json in your project directory.
5. Automatically configures and connects all 20 supported AI clients and IDEs (Amp, Antigravity, Claude, Cline, Codex, Copilot, Cursor, Factory, Gemini CLI, Goose, Grok, Junie, Kiro, LM Studio, opencode, Qodo, Qwen, VS Code, Warp, Windsurf).

---

Method 3: Global CLI Installation

Install gamemaker-mcp globally using npm:

npm install -g gamemaker-mcp

Then run commands from any terminal or PowerShell:

# Full automatic setup for a project:
gamemaker-mcp install "C:\Projects\MyGame\MyGame.yyp"

# Verify environment, runtime, and connection status for all 20 clients:
gamemaker-mcp doctor "C:\Projects\MyGame\MyGame.yyp"

# Connect a specific AI client (claude | antigravity | cursor | codex | qwen | vscode | windsurf | copilot | all):
gamemaker-mcp connect antigravity
gamemaker-mcp connect claude
gamemaker-mcp connect vscode
gamemaker-mcp connect cursor
gamemaker-mcp connect all

---

Method 4: Manual Client Configuration

If you prefer adding the MCP server to your AI client’s configuration file manually:

1. Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "gamemaker": {
      "command": "npx",
      "args": ["-y", "gamemaker-mcp"],
      "env": {
        "GAMEMAKER_MCP_MODE": "workspace-write",
        "GAMEMAKER_MCP_ALLOW_BUILD": "1"
      }
    }
  }
}

2. Google Antigravity (~/.gemini/antigravity.json)

{
  "mcpServers": {
    "gamemaker": {
      "command": "npx",
      "args": ["-y", "gamemaker-mcp"],
      "env": {
        "GAMEMAKER_MCP_MODE": "workspace-write",
        "GAMEMAKER_MCP_ALLOW_BUILD": "1"
      }
    }
  }
}

3. Cursor (%APPDATA%\Cursor\User\globalStorage\mcp.json)

{
  "mcpServers": {
    "gamemaker": {
      "command": "npx",
      "args": ["-y", "gamemaker-mcp"],
      "env": {
        "GAMEMAKER_MCP_MODE": "workspace-write",
        "GAMEMAKER_MCP_ALLOW_BUILD": "1"
      }
    }
  }
}

4. Qwen Code / CLI (~/.qwen/mcp.json)

{
  "mcpServers": {
    "gamemaker": {
      "command": "npx",
      "args": ["-y", "gamemaker-mcp"],
      "env": {
        "GAMEMAKER_MCP_MODE": "workspace-write",
        "GAMEMAKER_MCP_ALLOW_BUILD": "1"
      }
    }
  }
}

Environment variables

Complete Tool Catalog (165 Tools)

IDE Integration & Preferences (6 Tools)

Project & Navigation (10 Tools)

Static Analysis & Quality Audit (21 Tools)

GML, Assets & Resources (33 Tools)

Objects & Events (9 Tools)

Rooms, Shaders, Sequences, Timelines & Curves (16 Tools)

Snapshots & Integrity (4 Tools)

Builds & Igor Compiler Jobs (11 Tools)

Client Configuration (1 Tool)

Architecture, Systems & Powerhouse Code Generators (65 Tools)

Resources and Prompts

Resources (6)

• gamemaker://project/info — Live project summary and resource metadata.
• gamemaker://project/statistics — Live resource, line count, complexity, and dependency stats.
• gamemaker://runtimes — Detected GameMaker Studio runtimes and Igor.exe paths.
• gamemaker://gml/rules — Mandatory GML 2024+ strict syntax and coding rules for AI model context.
• gamemaker://snapshots — List of recorded project integrity snapshots.
• gamemaker://jobs/history — History of Igor build and package jobs.

Workflow Prompts (25)

• audit-gamemaker-project: Run a read-only structural, GML, shader, dependency, and statistics audit.
• debug-gamemaker-build: Use the persistent background job workflow to diagnose project build errors.
• safe-gamemaker-refactor: Snapshot, inspect references, preview patches, edit with hashes, validate, and compile.
• implement-gamemaker-shader-effect: Inspect and update a shader with cross-stage validation and a build check.
• restore-gamemaker-snapshot: Inspect a snapshot and request explicit confirmation before destructive restoration.
• create-state-machine: Generate a robust, clean state machine pattern for GameMaker objects.
• optimize-draw-events: Audit and optimize Draw events for batching, texture swaps, and state resets.
• refactor-gml-script: Refactor legacy argument0…15 scripts to modern GML 2024+ syntax and Feather JSDoc.
• write-clean-gml-script: Generate Feather-compliant, memory-optimized GML script with constructors and static methods.
• write-gml-unit-test: Create GML unit test suite, add assertion checks, and run them using the test framework.
• build-2d-lighting-system: Generate a complete 2D light raycaster, shadow caster struct, and shader pair.
• setup-inventory-system: Generate inventory database struct, slot UI controller, and save/load persistence.
• convert-legacy-ds-structures: Audit and convert legacy ds_list, ds_map, ds_grid, and ds_priority to GML 2D arrays & structs.
• setup-ai-behavior-tree: Build AI Selector, Sequence, and Action nodes for NPC/enemy decision making.
• setup-localization-csv-i18n: Scan project for hardcoded UI text strings, generate localization dictionary, and build translator.
• audit-gc-memory-leaks: Scan GML scripts for per-frame dynamic array/struct/DS allocations in step and draw events.
• setup-encrypted-save-system: Build encrypted JSON save/load state system with MD5/salt tamper checksums.
• setup-isometric-depth-sorting: Build 2.5D isometric depth sorting render pipeline code with Z-buffer toggles.
• setup-branching-dialogue-tree: Generate node-based dialogue tree struct system with choice branching and callback triggers.
• setup-multiplayer-packet-buffers: Build binary GameMaker buffer encoder/decoder struct code for multiplayer network packets.
• setup-ecs-architecture: Setup complete Entity-Component-System (ECS) framework for high entity count performance.
• setup-procedural-dungeon: Build procedural dungeon generator with rooms, corridors, and tilemap binding.
• setup-crt-retro-pipeline: Generate full-screen GLSL ES CRT filter with scanlines, screen curvature, and chromatic aberration.
• setup-rollback-netcode: Scaffold GGPO-style input ring buffer, client-side prediction, and resimulation rollback loop.
• setup-fighting-combo-buffer: Build fighting game directional and button combo buffer with fuzzy timing windows.

Recommended workflow

1. Inspect with gm_project_info, gm_asset_list, and the analysis tools.
2. Before a multi-file change, create a labeled snapshot.
3. Read every affected file and retain the returned SHA-256.
4. Preview exact GML patches where applicable.
5. Apply the smallest guarded edit. Stop and re-read if a hash is stale.
6. Run gm_project_validate after metadata changes.
7. Compile a trusted project with gm_job_start, then use gm_job_wait and gm_job_log.

Backups are stored under .gamemaker-mcp/backups; snapshots and job history live under .gamemaker-mcp/snapshots and .gamemaker-mcp/jobs.

Test any project

The smoke command starts the built MCP server in read-only mode, lists its tools, and calls project info, validation, statistics, GML analysis, and shader analysis:

npm run smoke -- "C:\path\to\Game.yyp"

Security model

• tool file paths are project-relative; absolute paths, traversal, NUL bytes, and symlink/junction escapes are rejected;
• only an allowlist of text extensions can be written;
• writes and Igor operations are disabled by default;
• existing-file writes require a SHA-256 read by the caller unless an explicitly supported force path is used;
• metadata edits preserve unknown fields through jsonc-parser and create backups;
• Igor is launched from a fixed executable with allowlisted actions and shell: false;
• only compile/package trusted GameMaker projects: GameMaker itself can run project compiler batch files, extensions, and build hooks;
• stdout is reserved for MCP JSON-RPC; server diagnostics go to stderr.

The server intentionally does not expose arbitrary shell commands, arbitrary YY/YPP overwrite, bulk asset deletion, or GUI automation. Binary sprite/audio import remains outside the current safe text-focused scope.

Compact tool discovery (default)

The project server initially advertises only gm_tools_search and gm_tools_enable. Search using words from a tool name or description, then enable the returned names. Disable finished tools with enabled: false. Pagination uses offset and limit. Clients must refresh their tool list after MCP tool-list change notifications. Set GM_MCP_TOOL_MODE=full for clients that require a static catalog or for legacy integrations. Project path checks, write permissions, input validation and hash checks still run in the original handlers.

Runtime tools

The runtime server provides 254 tools across 40 categories for inspecting and controlling a running GameMaker game. It starts with two category discovery tools; use list_tool_categories and load_category to enable what you need.

Run npm ci and npm run build in the repository root. Configure a second MCP server using node /absolute/path/gamemaker-mcp/runtime/server/build/index.js. For terminal use, run npm run start:runtime.

Install the GML extension using the installation guide. The default connection is 127.0.0.1:6705; configure it with GAMEMAKER_MCP_HOST and GAMEMAKER_MCP_PORT.

The runtime server controls the game independently of the project server’s read-only mode and filesystem sandbox. Use it in development builds. See the runtime guide and tool reference.