Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@grandMA2 Universal MCP Server set all stage wash fixtures to blue at 50% and store cue 1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Author: Xuân Văn 97 (Maka) — Minh Toan Event Company (Hai Phong, Vietnam)
Contact Email: makadino97@gmail.com
🇻🇳 Tiếng Việt • 🇬🇧 English • 📖 Full A-Z Manual (VI) • 🛠️ Instant Doctor
The grandMA2 Universal MCP Server is a lighting control bridge that directly connects modern AI Agents (including Google Antigravity IDE, Claude Desktop, OpenAI Codex CLI, Cursor, Windsurf, VS Code, Dola AI, Doubao, and ChatGPT Custom GPTs) to grandMA2 (onPC or physical consoles) using the Model Context Protocol (MCP).
Engineered and battle-tested in live concert environments by Xuân Văn 97 (Staff at Minh Toan Event Company, Hai Phong, Vietnam), this server eliminates unnecessary clutter, delivering sub-millisecond command execution and production-grade reliability for live stage performances.
Related MCP server: Eos MCP
flowchart LR
subgraph AI ["🤖 AI Agents"]
A1["Antigravity / Codex / Claude / Cursor"]
A2["Dola AI / Doubao / Custom GPT"]
end
subgraph MCP ["⚡ MCP Server (Pure Python)"]
S1["grandma2_mcp_server.py\n(Transport: stdio)"]
S2["ma2_mcp_http_server.py\n(Transport: HTTP/SSE /mcp)"]
DOC["check_connection.py\n(Automated Diagnostic Doctor)"]
end
subgraph GMA2 ["🎭 grandMA2 Console"]
NET["Telnet Port 30000\n(Global Settings = Enabled)"]
ENG["grandMA2 Command Engine"]
DMX["DMX 512 / Art-Net / sACN Output"]
LIGHT["💡 Stage Fixtures & grandMA 3D"]
end
A1 ==>|JSON-RPC stdio| S1
A2 ==>|HTTP POST/SSE| S2
S1 ==>|Async Telnet Socket| NET
S2 ==>|Async Telnet Socket| NET
NET --> ENG --> DMX --> LIGHTpip install -r requirements.txtLaunch grandMA2 onPC (or power on your physical console).
Go to: Setup $\rightarrow$ Console column $\rightarrow$ Global Settings.
Toggle Telnet to Enabled (Default Port: 30000, User: administrator, Pass: admin).
Mode | For AI Clients | Command |
Mode A (stdio) | Antigravity IDE, Claude Desktop, Codex, Cursor |
|
Mode B (HTTP) | Dola AI, Doubao, Cici, ChatGPT Custom GPTs |
|
Connecting Physical grandMA2 Consoles: Connect an Ethernet cable to eth0 on your console, set a static IP on the console (e.g. private LAN 192.168.x.x), enable Telnet in Global Settings, and set the environment variable GMA2_HOST=[MA2_CONSOLE_IP] on your AI host computer. The setup operates over an isolated, private LAN, air-gapped from the Internet to guarantee 100% security and anti-tamper protection. See HUONG_DAN_KET_NOI_CHI_TIET.md.
Experiencing connection difficulties or fixtures not responding? Run the built-in diagnostic doctor:
python check_connection.pyThis tool scans the Telnet port 30000, performs a handshake authentication test, and verifies the HTTP server status on port 8000, outputting precise actionable steps if any component is offline.
👉 For comprehensive troubleshooting diagrams and error resolution trees, see: HUONG_DAN_KET_NOI_CHI_TIET.md.
Connected through the Model Context Protocol (MCP), AI Agents operate as an end-to-end Virtual Lighting Programmer & Stage Operator:
Domain | What AI Can Do On grandMA2 | Example AI Commands |
1. 💡 Live Fixture & Attribute Control | • Dimmer 0–100%, Strobe Pulse, Random Strobe.• RGB/CMY color mixing, portrait CTO/CTB color temperature.• Pan/Tilt 540°/270°, automatic Fanning & fan symmetry.• Gobo wheel 1/2 selection, Prism rotation, Frost/Zoom/Iris.• Remote Lamp On/Off, motor reset for jammed fixtures. | "Set Fixtures 1 Thru 10 to Red, 80% dimmer, 30-degree fan out, light strobe" |
2. 🎬 Professional Show & Cue Programming | • Store new Cues, Merge parameters, Update existing Cues.• Discrete Fade/Delay timing per attribute (Dimmer 1s, Color 3s).• Manage Sequences, assign to Executor Faders, Go, Pause, Off, Top.• Blind Mode: Program unseen backstage cues directly during live shows without changing current stage output. | "In Blind mode, program Chorus cue with 2.5s fade and assign to Executor 1" |
3. 🎨 Preset Pool & Resource Management | • Manage all 9 standard Pools: Dimmer, Position, Gobo, Color, Beam, Focus, Control, Shapers, Video.• Create Groups (Odd/Even selection, Wings symmetry, Invert selection).• Create Worlds to isolate stage zones and apply safety attribute Filters. | "Create an Odd Fixtures Group and assign Cyan Color preset" |
4. ⚡ Macro Engine & Stage Automation | • Auto-generate and inject multi-line complex Macros into the MA2 Pool.• Timecode timeline sync (SMPTE / MIDI Timecode / LTC) aligned with audio.• Agenda scheduling for automated venue/theater runs. | "Generate Macro 150 to warm up fixtures and check all channels on boot" |
5. 🧠 Musical Intelligence & Stage Design | • Analyze song structure (Intro, Verse, Chorus, Drop, Bridge, Outro) and auto-generate matching Cue Lists.• Calculate BPM to dynamically adapt Speed Masters and chaser rates.• Recommend cinematic color palettes: Cyberpunk, Acoustic Warm, Dark Rock, Dreamy. | "Analyze this track lyrics and design a 5-cue sequence matching song emotions" |
6. 🛡️ Live Stage Emergency & System Admin | • Instant Programmer rescue ( | "Fixture 12 motor is stuck, immediately park it at 0 without stopping the show" |
7. 🎓 Interactive MA2 CLI Tutor & Coach | • Instant lookup for grandMA2 syntax with real-world examples.• Pre-flight syntax validation before sending commands to console.• Guided onboarding for new lighting technicians. | "How do I create a smooth rainbow color chaser across 20 par LEDs?" |
Add to .agents/mcp_config.json or .cursor/mcp.json:
{
"mcpServers": {
"grandma2": {
"command": "python",
"args": ["C:/path/to/grandma2-mcp-server/grandma2_mcp_server.py"],
"env": {
"GMA2_HOST": "127.0.0.1",
"GMA2_PORT": "30000"
}
}
}
}Add to %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"grandma2": {
"command": "python",
"args": ["C:\\path\\to\\grandma2-mcp-server\\grandma2_mcp_server.py"]
}
}
}Run run_dola_ma2_mcp.bat.
Enter the SSE endpoint: http://127.0.0.1:8000/mcp.
grandma2-mcp-server/
├── check_connection.py # 1-Click automated connection doctor & diagnostic tool
├── grandma2_mcp_server.py # Standard stdio MCP Server (Antigravity, Claude, Codex, Cursor)
├── ma2_mcp_http_server.py # HTTP / REST MCP Server (Dola AI, Doubao, Custom GPT)
├── xv97_lighting_bridge.py # Protected lighting bridge with obfuscated credentials
├── configs/ # Ready-to-use configuration templates for each AI tool
├── HUONG_DAN_KET_NOI_CHI_TIET.md # Master manual with architectural flows & troubleshooting (VI)
├── run_ma2_mcp.bat # Fast Windows launcher (stdio)
├── run_dola_ma2_mcp.bat # Fast Windows launcher (HTTP)
├── requirements.txt # Required Python libraries
├── README.md # English Documentation
└── README.vi.md # Vietnamese DocumentationXuân Văn 97 (Maka)
Affiliation: Technical Staff — Minh Toan Event Company (Công ty Sự kiện Minh Toán Hải Phòng)
Email: makadino97@gmail.com
Repository: https://github.com/vandiy064-byte/grandma2-mcp-server
Base of Operations: Hai Phong, Vietnam
Distributed under the MIT License. Free for commercial and private stage productions.
Copyright (c) 2026 Xuân Văn 97 (Minh Toan Event Company).
Developed and maintained by Xuân Văn 97 with practical field experience from productions at Minh Toan Event Company (Hai Phong).
If this project supports your live productions, please give it a ⭐ on GitHub! 🙌
This server cannot be deployed
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows