⚠️ 原型/概念验证 本项目是一个实验性实现，展示了通过MCP实现AI辅助照明控制。 本书不适用于生产用途。请自行承担风险。

MCP服务器，通过AI助手（Claude Desktop、VS Code Copilot等）控制grandMA3灯光控制台。

特色

• 直接执行 MA3 控制台命令
• 控制灯具（调光器、颜色、位置、gobo等）
• 存储和管理带有时序和触发器的提示
• 播放控制（返回、返回、关闭等）
• 执行推子和按钮控制
• 查询序列、提示和程序员内容
• 读取DMX输出
• 群组支持批处理操作

项目结构

快速启动

1.安装 Python 依赖

2.将Lua插件部署到MA3

将.env.example复制到.env，并配置你的路径：

然后部署：

或者手动复制plugin/mcp_server.lua到你的MA3插件文件夹：

• macOS： ~/MALightingTechnology/gma3_X.X.X/shared/resource/lib_plugins/mcp_server/
• Windows： %USERPROFILE%\MALightingTechnology\gma3_X.X.X\shared\resource\lib_plugins\mcp_server\

3.在MA3中启动插件

1. 在MA3中，进入插件→菜单

MA3-MCP

⚠️ Prototype / Proof of Concept
This project is an experimental implementation demonstrating AI-assisted lighting control via MCP. It is not intended for production use. Use at your own risk.

MCP server for controlling grandMA3 lighting consoles via AI assistants (Claude Desktop, VS Code Copilot, etc.).

Features

• Execute MA3 console commands directly
• Control fixtures (dimmer, color, position, gobo, etc.)
• Store and manage cues with timing and triggers
• Playback control (Go, Back, Off, etc.)
• Executor fader and button control
• Query sequences, cues, and programmer contents
• Read DMX output
• Group support with batch operations

Project Structure

ma3_mcp/
├── config.py      # Configuration management
├── ma3_comm.py    # File-based IPC with grandMA3
├── server.py      # MCP tools (@mcp.tool() definitions)
└── __init__.py

plugin/
├── mcp_server.lua    # grandMA3 Lua plugin
└── MCP Server.xml    # Plugin configuration

Quick Start

1. Install Python Dependencies

poetry install

2. Deploy the Lua Plugin to MA3

Copy .env.example to .env and configure your paths:

cp .env.example .env
# Edit .env with your MA3 installation path

Then deploy:

./deploy.sh

Or manually copy plugin/mcp_server.lua to your MA3 plugins folder:

• macOS: ~/MALightingTechnology/gma3_X.X.X/shared/resource/lib_plugins/mcp_server/
• Windows: %USERPROFILE%\MALightingTechnology\gma3_X.X.X\shared\resource\lib_plugins\mcp_server\

3. Start the Plugin in MA3

1. In MA3, go to Menu → Plugins
2. Create or select the “MCP Server” plugin
3. Start the plugin (it will poll for commands in the background)

4. Configure Your AI Assistant

For VS Code (GitHub Copilot):

The workspace settings are already configured. Just open the project in VS Code.

For Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "grandMA3": {
      "command": "poetry",
      "args": ["run", "python", "-m", "ma3_mcp.server"],
      "cwd": "/path/to/MA3-MCP"
    }
  }
}

Configuration

All configuration is done via environment variables. Copy .env.example to .env:

# IPC paths (defaults work for most setups)
MA3_IPC_DIR=/Users/Shared/MA3

# Plugin deployment path
MA3_PLUGIN_DIR=~/MALightingTechnology/gma3_2.3.2/shared/resource/lib_plugins/mcp_server

# OSC reload settings
MA3_OSC_HOST=127.0.0.1
MA3_OSC_PORT=8000

Platform Defaults

Communication Architecture

Uses file-based IPC for reliable cross-process communication:

MCP Client (Python)                    grandMA3 (Lua Plugin)
       │                                       │
       ├── Write command ──────────────────────┤