GMS2 MCP Server

MCP server for working with GameMaker Studio 2 projects in Cursor IDE.

What is this?

This MCP server parses and extracts information from GameMaker Studio 2 projects, providing developers and AI agents with quick access to project structure, GML code, and asset metadata.

Key features:

📊 For developers: export all project data in a readable format for study and analysis
🤖 For AI agents: rapid project structure understanding, significantly accelerating vibe-coding
🔍 Deep analysis: automatic scanning of objects, scripts, rooms, sprites and their relationships
⚡ Instant access: get information about any asset without opening GameMaker Studio 2

This solution makes working with GMS2 projects more efficient, especially when collaborating with neural networks.

Project Structure

gms2-mcp-server/
├── mcp-serv/
│   ├── mcp_server.py       # MCP server with 7 tools 
│   └── gms2_parser.py      # GameMaker Studio 2 project parser 
├── docs/
│   ├── README.md           # Documentation in English
│   └── README_RU.md        # Documentation in Russian
├── requirements.txt        # Dependencies (mcp==1.11.0, python-dotenv==1.1.1)
└── venv/                   # Python virtual environment (created by user)

Additionally, the user creates:
└── .cursor/mcp.json       # Cursor IDE configuration (includes project path)

Installation

1. Clone the repository

git clone https://github.com/Atennebris/gms2-mcp-server
cd gms2-mcp-server

2. Create virtual environment

# Create venv
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Linux/Mac)
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

Current dependencies:

mcp==1.11.0 - official Python SDK for Model Context Protocol
python-dotenv==1.1.1 - loading configuration from .env files

4. Cursor IDE configuration

Create a .cursor/mcp.json file in your project root with the following content:

Complete configuration with project path (recommended):

{
  "mcpServers": {
    "gms2-mcp": {
      "command": "python",
      "args": ["C:/Users/YourName/Desktop/gms2-mcp-server/mcp-serv/mcp_server.py"],
      "env": {
        "GMS2_PROJECT_PATH": "C:/Users/YourName/Downloads/Your GMS2 Project"
      }
    }
  }
}

⚠️ Important:

Replace the path in args with the absolute path to your MCP server folder!
Replace the path in env.GMS2_PROJECT_PATH with the absolute path to your GMS2 project folder (contains .yyp file)!
Use forward slashes / even on Windows

Option 2: Global configuration (for all projects)

In Cursor IDE, open settings
Go to Tools & Integrations section
Click New MCP Server button at the bottom
This will open the global mcp.json file
Add the same configuration there

Launch architecture:

Cursor IDE directly launches python mcp-serv/mcp_server.py
mcp_server.py loads project path from environment variable GMS2_PROJECT_PATH (set in mcp.json)
Parser gms2_parser.py provides functionality for working with GMS2 projects

5. Restart Cursor IDE

After configuring, restart Cursor IDE. In Cursor IDE: Open command palette and check MCP servers status.

Features

After successful installation, 7 tools will be available in Cursor IDE:

🔍 scan_gms2_project - scan GMS2 project structure (count assets, find GML files)
📄 get_gml_file_content - read content of specific GML file
🏠 get_room_info - get detailed information about rooms from .yy files
🎯 get_object_info - analyze objects and their events from .yy files
🖼️ get_sprite_info - sprite information (dimensions, frames, settings)
📊 export_project_data - export all project data to text format
📋 list_project_assets - list all assets by categories (Objects, Scripts, Rooms, Sprites, etc.)

Features:

Support for projects with spaces in paths (via environment variables)
Automatic project structure detection
Export in human-readable format
Full compatibility with .yyp and .yy file formats
Simplified configuration through mcp.json only

Usage Example

In Cursor IDE (AI agent) you can ask:

"Show my GMS2 project structure"
"Read obj_player object code"
"What rooms are in the project?"
"Export all project data"

System Requirements

Python: 3.8+ (recommended 3.10+) - tested on 3.12
GameMaker Studio 2: Any version with .yyp projects
Cursor IDE: With MCP support
OS: Windows 10/11 (tested)

Troubleshooting

MCP server shows red status

Check absolute path in .cursor/mcp.json (both args and env.GMS2_PROJECT_PATH)
Make sure venv is created and dependencies are installed
Check project path in env.GMS2_PROJECT_PATH section of mcp.json

Server doesn't find the project

Make sure the path in env.GMS2_PROJECT_PATH is correct
Path should point to folder with .yyp file
Use forward slashes / even on Windows

Tools don't display (0 tools)

Restart Cursor IDE
Check that Python interpreter is accessible
Test server manually: python mcp-serv/mcp_server.py

Import errors or path issues

All import and path issues have been resolved in the current version:

gms2_parser.py is now in the same directory as mcp_server.py
Project path is configured directly in .cursor/mcp.json via environment variables
No config files or wrapper scripts needed

Technical Information

Dependencies

mcp==1.11.0 - official Python SDK for Model Context Protocol
python-dotenv==1.1.1 - loading configuration from .env files

Architecture

The project consists of two main components:

mcp-serv/gms2_parser.py - GameMaker Studio 2 project parser
mcp-serv/mcp_server.py - MCP server with 7 tools for analysis

What's Changed

Version 2.1 improvements:

✅ Simplified project structure (no wrapper scripts)
✅ Fixed all import and path issues
✅ Removed config.env dependency - all configuration now in mcp.json
✅ Consolidated all server code in mcp-serv/
✅ Project path configured via environment variables in mcp.json
✅ Improved error handling and debugging

Project History

This MCP server was created based on the idea and functionality of the vibe2gml project, which was also developed to simplify and accelerate vibe-coding in the GameMaker Studio 2 game engine.

vibe2gml is a tool for exporting GMS2 projects to text format for working with AI agents. Our MCP server develops this idea by providing:

Direct integration with Cursor IDE through the MCP protocol
A richer set of tools for project analysis
Real-time data access without file export
Simplified configuration and setup

Additional Resources

Documentation

docs/README.md - main documentation in English
docs/README_RU.md - main documentation in Russian

Useful Links

MCP Python SDK - official SDK
MCP Documentation - protocol documentation
GameMaker Studio 2 - official GameMaker website
vibe2gml - original project that inspired the creation of this MCP server