ma3-mcp-free

# MA3 MCP Server **Blacklist Tech** | grandMA3 Model Context Protocol Server **Version:** 1.0.0 · **License:** MIT · **Status:** Stable Core --- ## Overview The **MA3 MCP Server** is a high-performance interface that bridges the gap between AI assistants (like Claude) and grandMA3 lighting consoles. By leveraging the Model Context Protocol (MCP), it allows for natural language control of complex lighting systems via high-speed OSC communication. Designed for lighting designers, programmers, and enthusiasts, this server provides a robust, offline-first foundation for modern lighting workflows. ### Key Features - **Natural Language Control**: Patch, select, and manipulate fixtures using plain English. - **Unified Toolset**: Includes tools for patching, parameter control, playback, and data queries. - **OSC Integration**: Direct, low-latency communication with grandMA3 Hardware and onPC. - **Safety First**: Integrated command validation prevents destructive accidental commands. - **100% Offline**: No internet connection required; runs entirely on your local network. --- ## Core Architecture ``` AI Assistant (LLM) │ ▼ [MCP Protocol] MA3 MCP SERVER │ ▼ [OSC @ Port 8000] grandMA3 Console ``` The server acts as a translator, converting high-level AI intent into byte-precise OSC commands that grandMA3 understands. --- ## Project Structure ``` ma3-mcp-free/ ├── src/ │ ├── server.py # MCP Server entry point │ ├── osc_client.py # OSC Communication layer │ ├── ma3_commands.py # Command-line string builders │ ├── tools/ # MCP Tool definitions │ │ ├── fixture_tools.py # Patching & Selection │ │ ├── playback_tools.py # Sequence & Fader control │ │ └── query_tools.py # Data retrieval │ └── parsers/ # OSC Response handlers ├── tests/ # Unit & Integration tests ├── config/ # YAML configuration profiles └── scripts/ # Deployment scripts (systemd/bash) ``` --- ## Quick Start ### 1. Prerequisites - Python 3.9+ - grandMA3 onPC or Console (on the same network) ### 2. Installation ```bash git clone https://github.com/blacklist-tech/ma3-mcp-server cd ma3-mcp-server python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt ``` ### 3. Configuration Copy the example config and update it with your console's IP address: ```bash cp config/config.example.yaml config/config.yaml ``` ### 4. Run ```bash python -m src.server ``` --- ## Feature Set | Component | Capability | Description | |---|---|---| | **Patching** | `patch_fixture` | Patch single or multiple fixtures to specific universes. | | **Selection** | `select_fixtures` | Standard MA3 selection syntax support (e.g. '1 Thru 10'). | | **Control** | `set_fixture_values` | Direct attribute manipulation (Dimmer, Pan, Tilt, etc.). | | **Playback** | `trigger_sequence` | Fire cues and sequences with name support. | | **Hardware** | `set_fader` | Physical or virtual fader manipulation. | | **Audit** | `get_patch_list` | Export and review the current console patch. | --- ## Advanced Automation & Enterprise Support The MA3 MCP Server is designed to be extensible. For enterprise environments requiring: - **AI-Powered Show Analysis** (Automatic conflict detection & optimization) - **Automatic Tech Pack Generation** - **Advanced 3D Spatial Layout Tools** - **Multi-Client Rate Limiting & Audit Logging** Please see our **Enterprise & Pro** documentation or visit [blacklisttech.com](https://blacklisttech.com). --- ## License Distributed under the **MIT License**. See `LICENSE` for more information. --- *Built with ❤️ by Blacklist Tech · [blacklisttech.com](https://blacklisttech.com)*