GMS2 MCP Server

# 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 ```bash git clone https://github.com/Atennebris/gms2-mcp-server cd gms2-mcp-server ``` ### 2. Create virtual environment ```bash # Create venv python -m venv venv # Activate (Windows) venv\Scripts\activate # Activate (Linux/Mac) source venv/bin/activate ``` ### 3. Install dependencies ```bash 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): ```json { "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](https://github.com/zsturg/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](https://github.com/modelcontextprotocol/python-sdk) - official SDK - [MCP Documentation](https://modelcontextprotocol.io/introduction) - protocol documentation - [GameMaker Studio 2](https://gamemaker.io/) - official GameMaker website - [vibe2gml](https://github.com/zsturg/vibe2gml) - original project that inspired the creation of this MCP server