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)

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

Launch architecture:

1. Cursor IDE directly launches python mcp-serv/mcp_server.py
2. mcp_server.py loads project path from environment variable GMS2_PROJECT_PATH (set in mcp.json)
3. 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 pa

... View full README on GitHub