GMS MCP

Give your AI assistant tools to understand, edit, build, and interact with your GameMaker game.

GMS MCP connects an MCP-capable AI client to a local GameMaker project. It gives the assistant structured operations for GameMaker assets and metadata, code navigation, project diagnostics, and Igor builds. An optional TCP bridge lets it send supported commands to a running game and read instrumented game logs.

Use it from Cursor, Codex, Claude Code, or another compatible client. Prefer the terminal? The package also includes the gms CLI; no AI client is required for CLI operations.

GMS MCP is an independent, open-source project by Ampersand Game Studios, not an official GameMaker product. It is a game-development tool, not a project-management or social-media service.

Quick start · Capabilities · Example workflows · Safety and privacy · Troubleshooting · Documentation

What you can do

Availability depends on the selected tool profile, client capabilities, and installed GameMaker toolchain. The bridge is not a GML hot-reload system, and GMS MCP does not provide automatic synchronization with the GameMaker IDE.

Quick start

1. Install

You need Python 3.11 or newer, a GameMaker project containing a .yyp file, and an MCP-capable client. Building and running also require an installed GameMaker runtime, the appropriate licence/access credentials, and any target-specific SDKs. Project inspection does not require the GameMaker IDE to be running.

With pipx installed:

pipx install gms-mcp

The package installs three commands:

For sprite image imports, install the optional image dependency with pipx inject gms-mcp 'Pillow>=13,<14'.

2. Connect your client

Open a terminal in your game's project folder, not the GMS MCP source repository. Run the command for your client:

# Cursor
gms-mcp-init --client cursor --scope workspace --action app-setup

# Codex
gms-mcp-init --client codex --scope workspace --action app-setup --config-path .codex/config.toml

# Claude Code
gms-mcp-init --client claude-code --scope workspace --action app-setup

These canonical setup commands default to the read-only `safe` profile. They write client configuration; they do not grant the assistant project-editing or build tools. Read and complete any client registration instructions printed by the installer, then restart the client's MCP connection.

Codex: the explicit --config-path writes to .codex/config.toml, the project-scoped configuration supported by Codex for trusted projects. Without that override, the initializer writes a .codex/mcp.toml snippet that needs separate registration. Keep the override on subsequent setup/profile/check commands. Review existing configuration before merging, and only trust projects you recognize. See OpenAI's MCP configuration guide.

Other installer targets include antigravity (alias gemini), vscode, windsurf, openclaw, and generic. Some targets generate configuration for you to import rather than activating a native client connection automatically. The claude-desktop target uses --scope global and generates a plugin bundle. Check the compatibility matrix for supported scopes and the client guide for capability limits.

3. Verify the connection

From the same project folder:

gms-mcp doctor --project
gms-mcp-init --client cursor --scope workspace --action check

Replace cursor with your chosen client; for the Codex setup above, also add --config-path .codex/config.toml. Configuration checks do not prove that a client has connected: in a new assistant session, ask:

Use GMS MCP to call gm_capabilities and gm_project_info. Confirm the connected project and available tools, then summarize the game without changing anything.

Successful tool responses from the intended project confirm the connection. Missing runtime or licence checks affect builds; they do not necessarily prevent read-only project inspection.

Enable editing and additional tools

Start read-only to check the project boundary, then choose the access you need:

To enable editing and the wider tool catalogue for Cursor:

gms-mcp-init --client cursor --scope workspace --action app-setup --profile full

Use your chosen client and supported scope instead of cursor/workspace where appropriate. `standard` and `full` allow writes and do not require every mutation to be a dry run. Commit or back up your game first, avoid concurrent IDE edits, and restart the MCP connection after changing a profile. These profiles configure the MCP server, not the permissions of the standalone gms CLI or your AI client's other tools.

To expose selected domains instead of everything:

gms-mcp-init --client cursor --scope workspace --action app-setup --profile standard --toolsets core,assets,events,rooms

Optional domains: assets, bridge, docs, events, live-reload, maintenance, map, resourcetool, rooms, runtime, and texture-groups. Call gm_capabilities to see what is actually enabled. safe accepts only the read-only core surface; it cannot be combined with extra toolsets.

Try it with your assistant

These are example requests, not claims that an AI will complete every task correctly. Inspect the resulting changes and verification results.

Understand the game (available with safe):

Inspect this project. Explain the startup room, main objects, and their relationships. Identify missing asset references without changing files.

Add a feature (enable full or the relevant editing domains):

Add a collectible coin object using the existing project conventions. Put it in the correct asset folder, add its events, place one in the startup room, then validate the changes and compile. Report any remaining errors.

Refactor with context (requires editing access):

Find every reference to obj_enemy. Preview a rename to obj_enemy_basic, explain what will change, and wait for my approval before applying it. Validate the project afterwards.

Investigate a running game (requires bridge, build access, and bridge setup):

Check the bridge setup, run the game with the bridge enabled, verify the connection with a ping, and inspect recent instrumented logs. Stop the managed run when finished.

Clients that expose MCP prompts can also use create-feature, diagnose-project, safe-refactor, compile-fix-retry, and inspect-live-game. Fetching a prompt does not execute tools or modify the project; its instructions adapt to the active profile.

Work with a running game

The optional bridge connects the MCP server to GML code inside your game over local TCP. Use it for supported runtime commands and instrumented logging, not arbitrary code hot reload.

1. Enable the bridge toolset and editing/build access.
2. Install the bridge assets and ensure a __mcp_bridge instance is created in the startup room. gm_bridge_enable_one_shot combines asset installation and room placement; gm_bridge_install alone does not place an instance.
3. Check the platform requirements in the bridge guide. Windows networking may require changing the GameMaker sandbox option; understand that change before applying it.
4. Run with gm_run(background=true, enable_bridge=true), check gm_bridge_status, then send ping through gm_run_command.
5. Read gm_run_logs and stop the managed session with gm_run_stop when done.

Bridge logs come from __mcp_log(...); they are not a scrape of every show_debug_message(...) or IDE console message. Only one game should use the bridge port at a time. Treat the bridge and its installed assets as development instrumentation; review or remove them before distributing your game.

Use the CLI without an AI client

Run these from your game's project folder:

gms --help
gms --project-root . texture-groups list
gms maintenance normalize-names

The normalization command previews naming changes. Add --fix only when you intend to apply them. To create an asset or compile:

gms --project-root . asset create script my_function --parent-path "folders/Scripts.yy"
gms --project-root . run compile

Use an existing logical folder from your game in place of folders/Scripts.yy. Asset creation writes project files, and compilation requires the GameMaker toolchain. See the CLI documentation and gms <command> --help for available arguments.

Safety and privacy

• Choose the project deliberately. Each MCP server process pins one GameMaker project at startup and checks project-relative access against that boundary. Use separate server entries for separate projects. Sprite PNG inputs must be inside the pinned project.
• Project context goes to your client. Tools intentionally return source and asset metadata from the selected game. Only connect a project whose contents you are willing to share with that AI client/provider. A local server does not make a cloud AI conversation private.
• Use version control or backups. Guarded operations, validation, and rollback mechanisms reduce risk; they do not guarantee that every AI edit is correct or recoverable. Avoid editing the same files simultaneously in the GameMaker IDE and through an assistant.
• Usage telemetry is off by default. Interactive CLI setup can ask for consent; MCP startup never prompts on stdio. Default usage events exclude paths, command arguments, output, project names, usernames, emails, hostnames, and persistent IDs. Check or disable it with gms telemetry status or gms telemetry disable.

Events include a random per-process session ID; a persistent install hash is separately opt-in. The receiver sees transport network metadata. Local pending events are limited to seven days, 1,000 events, and 1 MiB; disabling clears them and prevents subsequent uploads. The service retains raw events for 90 days and identifier-free aggregates for 24 calendar months. See release and telemetry operations.

• Local does not mean offline. Documentation lookup and update checks can access online services. SDK OpenTelemetry spans require a host-configured exporter; GMS MCP does not configure an external tracing service itself.
• Keep diagnostics private. Automatic MCP diagnostic logs live outside the game under ~/.gms-mcp/logs/<opaque-project-id>/. Review logs and screenshots before sharing them; never attach credentials or proprietary game files to a public issue.

The generated client configurations use stdio, with the client starting a local server process. An optional bearer-authenticated Streamable HTTP transport is restricted to loopback, checks Host/Origin headers, and limits request bodies to 1 MiB. It is not a public or shared remote-server deployment mode. Follow the HTTP configuration guide; keep its token out of committed configuration and logs.

Compatibility and limits

GameMaker: build/run defaults follow the host platform: Windows, macOS, or Linux. VM and YYC compilation depend on installed toolchains; isolated macOS runs currently support VM only and reject YYC before launch. GMRT labels are currently rejected because the required Igor command-line contract is not implemented. Runtime selection and pinning are available through gm_runtime_list, gm_runtime_pin, gm_runtime_unpin, and gm_runtime_verify in the runtime toolset.

AI clients: installer support means configuration generation and repository tests, not certification of every client release. Optional dashboard rendering, resource subscriptions, and Resolve choices depend on negotiated client capabilities. The dashboard also returns text and structured data without MCP Apps support.

MCP: the package pins Python SDK mcp and mcp-types to 2.3.0. Compatibility tests cover protocol 2026-07-28 and legacy 2025-11-25, including real stdio and authenticated local HTTP calls, header-routed project selection, and omitted legacy request metadata. SDK/package version numbers are distinct from protocol revision dates. Modern-mode features include cache hints, live resource updates after mutations or external edits, URI templates, and multi-round Resolve choices for exceptional mutations. See the runtime capability contract.

<details> <summary>Optional official ResourceTool validation</summary>

This integration checks compatibility with YoYo's ResourceTool through an installed official gm-cli. It is disabled by default, is not an official affiliation, and is not a mutation backend.

Configure the server environment with the opt-in resourcetool toolset, an absolute executable path, its independently verified SHA-256, and the fixed argument contract:

GMS_MCP_TOOLSETS=resourcetool
GMS_MCP_RESOURCETOOL_ENABLED=1
GMS_MCP_RESOURCETOOL_EXECUTABLE=<absolute path to the trusted gm-cli executable>
GMS_MCP_RESOURCETOOL_SHA256=<verified SHA-256 of that executable>
GMS_MCP_RESOURCETOOL_ARGUMENTS_JSON=["resourcetool","eval","resource list","{project_copy_yyp}"]

These are configuration values, not a shell script. Do not enable them in the read-only safe profile.

gm_resourcetool_validate requires the configured gm-cli executable to match its pinned SHA-256, rejects symlinks and private-file/content conventions, and copies the complete project into a task-owned temporary directory. It runs the fixed resource list command in an OS sandbox that blocks network access, live-project reads, and host writes; platforms without the required sandbox fail closed. ResourceTool may normalize project metadata while loading even for this query, so the complete copy is checksummed before and after and any rewrite is reported as a failed validation. Child output is suppressed, and cleanup happens before returning. A rewrite, timeout, nonzero exit, ambiguous .yyp, identity mismatch, private data, or altered command contract fails closed. This validates ResourceTool project-list compatibility; it is not a mutation backend.

</details>

Troubleshooting

Codex setup and checks

Use the same explicit configuration path as the quick start:

gms-mcp-init --client codex --scope workspace --action check --config-path .codex/config.toml
gms-mcp-init --client codex --scope workspace --action check-json --config-path .codex/config.toml
gms-mcp-init --client codex --scope workspace --action setup --config-path .codex/config.toml --dry-run

Checks redact secret-like values. Dry-run setup previews only the target server entry without writing, omitting unrelated config and replacing private paths. Workspace Codex configuration stores project roots relative to the repository; roots outside that workspace are rejected. Global configuration deliberately leaves project resolution to the server's startup workspace. The older --codex-check, --codex-check-json, and --codex-dry-run-only helpers target the initializer's default snippet/global paths, not the custom project config above.

Updates

pipx upgrade gms-mcp
gms-mcp doctor

Restart your MCP connection after upgrading. gm_check_updates and gms://system/updates expose update status to clients. Bundled hooks can provide once-daily reminders where installed; not every package installation has an active reminder hook.

Documentation

The repository also includes a Claude plugin with workflow skills and hooks. The gms skills install command supports skill installation, including gms skills install --openclaw --project for workspace-scoped OpenClaw skills. Skills are instructions for the assistant, not additional server permissions.

Development and verification

Contribute against dev; maintainers promote dev → pre-release → main. See Contributing.

From a source checkout, using uv:

uv sync --frozen --all-extras --python 3.12
uv run --frozen pytest -q
uv run --frozen pytest cli/tests/python/test_final_verification.py
uv run --frozen python scripts/generate_quality_reports.py

CI runs core tests on Linux and Windows across Python 3.11–3.13, plus macOS runner/session tests across Python 3.11–3.13. It also checks MCP protocol behaviour, locked dependencies for known vulnerabilities, package privacy boundaries, and tool-registration parity. These checks are evidence of tested behaviour, not a guarantee that a project or dependency is free of defects.

Release publication requires passing real GameMaker 2024 and 2026 LTS certification from the exact push-triggered CI run on disposable Linux, Windows, and macOS runners. A generated MCP fixture alone does not establish compile/run compatibility. Build archives must also pass the public-file allowlist; local reports, service operations, development tests, and CI configuration are excluded from published packages.

<details> <summary>Maintainer smoke tests and release gates</summary>

Run the full Python runner, final verification tests, and quality reports before promotion:

uv run --frozen python cli/tests/python/run_all_tests.py
uv run --frozen pytest cli/tests/python/test_final_verification.py
GMS_MCP_TOOLSETS=all uv run --frozen python scripts/run_mcp_tool_smoke.py \
  --init-minimal-base \
  --base-project build/mcp-smoke/base-project \
  --work-root build/mcp-smoke/work \
  --output build/reports/mcp_tool_smoke_report.json
uv run --frozen python scripts/generate_quality_reports.py

The report generator enforces 85% overall coverage, 50% per-module coverage, and runtime/source tool-registration parity. Executed MCP smoke calls are reported separately from static test-source references. Quality artifacts include the coverage/JUnit reports, TEST_COVERAGE_REPORT.md, MCP_TOOL_VALIDATION_REPORT.md, mcp_tool_smoke_report.json, and quality_summary.json.

On a configured GameMaker machine, run both version-authored fixtures:

uv run --frozen python scripts/run_real_gamemaker_smoke.py \
  --fixture-name gm-2024 \
  --expected-runtime-version 2024.14.4.268 \
  --required

uv run --frozen python scripts/run_real_gamemaker_smoke.py \
  --fixture-name gm-2026-lts \
  --expected-runtime-version 2026.0.0.23 \
  --required

Publication is chained to successful push-triggered CI on dev, pre-release, or main; skipped or missing real-GameMaker certification blocks PyPI publication. Keep GAMEMAKER_ACCESS_KEY in the branch-restricted gamemaker-ci environment, never in source or repository-wide configuration. A manually dispatched CI run with run_real_gamemaker_smoke can validate the licensed matrix but cannot trigger publication. Confirm release-bound CI passes on main after promotion.

</details>

Support and licence

Report reproducible bugs or request features through GitHub Issues. Include the GMS MCP version, OS, client, GameMaker runtime if relevant, and sanitized reproduction steps. Use a minimal non-proprietary project rather than uploading your working game. Do not post secrets or exploitable security details publicly; use GitHub's private vulnerability reporting if available.

GMS MCP is released under the MIT licence. GameMaker and your AI client's own terms and licensing still apply. If the tools help you build your game, a GitHub star helps other developers find the project.