gma3-mcp

An MCP server for grandMA3 onPC. Connect an MCP client to inspect show data, program fixtures, store and edit cues, control playback and faders, and search the manual installed with onPC. Arbitrary Lua execution is available as a separate, opt-in capability.

Get started

Choose the guide for the computer running grandMA3 onPC and your MCP client:

Both guides cover building the server, copying the plugin, importing it into onPC, configuring your MCP client (ChatGPT desktop, Claude Code or Claude Desktop), and checking the connection. Start with the native setup for your platform. For ChatGPT in a browser, see ChatGPT web.

Running the MCP client on a different computer? See remote access over SSH. For container deployment, see Docker.

The documented live verification baseline is grandMA3 onPC 2.5.1.0 on macOS. Windows instructions are provided, but this does not establish equivalent live validation on Windows or other onPC versions. See the tested platform/version matrix for the distinction between live probes, automated checks and deployments still awaiting qualification.

What you can do

See the complete tool and configuration reference. Workflow tools report command outcomes and read-back verification separately; an uncertain outcome requires inspecting console state before trying the command again. Some console data is unavailable through the API and is reported as a limitation, rather than invented or returned as a misleading zero.

How it works

MCP client → stdio → Node.js MCP server → local TCP bridge → grandMA3 onPC

The Lua bridge plugin runs inside onPC and listens on 127.0.0.1:9800. The MCP server translates tool calls into bridge requests. Both parts are required for show inspection and workflow tools. The plugin also carries three instance-based console interaction modules (owned input sessions, read-only feedback, continuous-control admission) as extra components of the same XML. Input is off by default; the operator enables it per start on the console keyboard backend (input=keyboard, real key presses through Keyboard()), the owned-Quickey backend (input=quickey, real key presses through a provisioned Quickey bank on reserved executors), both on one instance (input=mixed, the Quickey default with per-key Keyboard() overrides; combinations that are not qualified are refused) or the fake backend (input=fake, events recorded only). The structured input tools (gma3_hardkey, gma3_keyboard, gma3_type, gma3_input_sequence, gma3_input_interaction, status and release) expose it; while input is owned by any client, the bridge refuses commands, property changes, playback, faders and Lua from every client with an explicit [busy] error instead of running them into a changed console state. The read-only feedback tool (gma3_feedback) observes command text, masters, Preview, page, selection, executor assignment, fader levels and sequence activity without Lua, input or a free bridge.

gma3_command also supports write-only OSC when OSC input is configured in onPC. Automatic fallback happens only if the bridge cannot be reached before dispatch; a command with an uncertain result is never automatically replayed. gma3_start_bridge can start an already-imported plugin over OSC. OSC is optional for the normal bridge setup and is not forwarded by an SSH tunnel.

Before using it in a show

• Tools operate on the live show and can change the programmer, playback and stored show data. Start with a disposable show and read-only queries. Save your show when you want show changes to persist; commands and enabled Lua can also perform file operations.
• The bridge has no authentication. It accepts loopback connections only, so local applications can access it. Use the documented SSH setup for remote access.
• Arbitrary Lua is disabled on the bridge by default. Its execution budget is best effort and is not a sandbox or a cancellation guarantee. Read Lua execution and hook policy before enabling it.
• Commands that open a blocking dialog can stall the plugin. Use /NoConfirmation where appropriate.

Documentation

• Bridge import, startup, updates and troubleshooting
• Configuration, tools, workflow results and bridge protocol
• Workflow details: fixtures, cues, executors, inspection, console input, console feedback, patch, playback configuration, groups and MAtricks, presets, phasers, recipes, speed masters and tempo, macros, timecode shows
• Show-building features (SB-01 … SB-08)
• Show setup from scratch: field-test gaps and fixes (SU-01 … SU-10)
• Hardkey, keyboard and feedback feature requests and evidence, console interaction modules
• Dialog control and dialog-free patching: plan and evidence
• Optional Lua execution
• Remote access over SSH and Docker
• Tested platform/version matrix and pinned modules for independent consumers
• Development and automated tests, live test procedure

Contributing and security

Please follow the code of conduct. See accessibility guidance and reporting for interface and documentation barriers. See contribution guidance for bug reports, development checks and pull requests. Report suspected vulnerabilities privately using the security policy.

License

MIT

grandMA3 and MA Lighting are trademarks of MA Lighting Technology GmbH. This project is independent and is not affiliated with, endorsed by, or supported by MA Lighting. No MA Lighting documentation, code, or libraries are redistributed here: the help tool reads the manual from your own onPC installation at runtime, and the bridge plugin uses the LuaSocket and JSON libraries already shipped inside onPC.