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 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

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

Server doesn't find the project

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

Tools don't display (0 tools)

1. Restart Cursor IDE
2. Check that Python interpreter is accessible
3. 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