Skip to main content
Glama
grandma2-mcp

grandma2-mcp

by RaSteaks

grandma2-toolkit

通过 MCP、CLI 和 Agent Skill 控制 grandMA2 onPC 与 MA3D。

  • 双端连接:自动识别 onPC / MA3D,查询 Show、灯具和播放对象。

  • 场景与编程:执行命令,调整灯具位置、安装方向和相机。

  • 备份与验收:导出 XML、备份 Show、保存 MA3D 截图和操作记录。

快速开始

准备 Python 3.11+、uv,启动 onPC / MA3D 并启用 Telnet。在仓库目录运行:

uv sync --locked

$credential = Get-Credential -UserName administrator -Message 'MA2 Telnet 登录'
$env:MA2_USER = $credential.UserName
$env:MA2_PASSWORD = $credential.GetNetworkCredential().Password

uv run grandma2 connections

默认连接 127.0.0.1,探测 30000 / 30001,按运行时身份区分两端。默认只读。

Related MCP server: touchbridge

使用方式

MCP

将 examples/mcp.json 中的配置加入 MCP 客户端,修改仓库路径,并为服务进程提供 MA2_PASSWORD。也可使用以下启动命令:

uv run --locked --directory G:/GitHub/grandma2-toolkit grandma2-mcp

工具

功能

ma2_connections

同时连接 onPC 与 MA3D

ma2_status

读取 Show、运行时和网络状态

ma2_list

查询对象及编号范围

ma2_execute

批量执行命令,遇错停止

ma2_export

导出原生 XML 并计算内容指纹

ma2_backup

保存、备份 Show 并计算 SHA256

ma3d_transform

调整灯具安装位置、朝向或相机

ma3d_capture

保存 MA3D 窗口截图并返回图片

Skill

入口:ma2-control / SKILL.md。支持项目 Skill 的客户端可直接发现,也可让 Agent 读取该文件。

使用 $ma2-control 同时连接 onPC 和 MA3D,只读检查当前 Show 与 Page 3。

使用 $ma2-control,保留 Page 3 编程,先备份,再调整指定地面灯的安装方向并截图验收。

CLI

# 查询、导出与截图
uv run grandma2 list 'Executor 3.1 Thru 3.8'
uv run grandma2 --target ma3d list 'Camera 50'
uv run grandma2 export 'Page 3'
uv run grandma2 capture --window-title 'MA 3D'

# 开启写入;将 Show 名称和对象编号替换为现场实际值
$env:MA2_ALLOW_WRITE = '1'
uv run grandma2 backup --expect-show codex
uv run grandma2 --target ma3d transform 'Camera 50' --expect-show codex --values '{"z":12.8,"rx":-2}'
uv run grandma2 execute --expect-show codex --commands-file examples/commands.readback.json

--target 放在子命令前,默认 onpc。位置单位为米、旋转为度、相机 FOV 为弧度。 更多命令见 命令参考。

配置

通过进程环境变量配置,无内置密码。

变量

默认值

说明

MA2_HOST

127.0.0.1

目标主机

MA2_PORTS

30000,30001

候选 Telnet 端口

MA2_USER

administrator

登录用户

MA2_PASSWORD

—

必填

MA2_ALLOW_WRITE

0

设为 1 启用写入

MA2_TIMEOUT

15

响应超时,单位秒

MA2_OUTPUT_DIR

仓库 .data

日志、备份、导出和截图目录;安装 wheel 后建议显式设置

MCP 客户端不一定继承终端环境变量,请确认密码已传给服务进程。

使用须知

  • 写入需匹配 Show:开启写入后仍需提供 expected_show。批次失败不会回滚,超时后应先查询状态再决定是否重试。

  • 区分场景与编程:安装朝向不是 Cue 的 Pan/Tilt;MA3D 场景修改可能同步到 onPC。两端同名 Show 不代表已加入同一会话。

  • 本机能力:文件导出、备份仅支持本机运行时;截图需要 Windows 上可见、未最小化的 MA3D 窗口,效果仍需查看图片确认。

  • 控制网络:Telnet 明文传输,仅用于受信任网络。通用命令接口可执行 Lua、删除等操作,写入开关不是权限沙箱。

开发

uv sync --locked --group dev
uv run pytest
uv run ruff check .
uv build

AGPL-3.0

Available Tools

8 tools
ma2_backupB

Save onPC Show, wait for asynchronous completion, copy a new backup and return SHA256. Write gate applies.

Inputs: expected_show (required). Returns: object

ma2_connectionsB
Read-onlyIdempotent

Connect onPC and MA3D simultaneously; return runtime identity, Show and session state for each.

Inputs: no named parameters. Returns: object

ma2_executeA
Destructive

Execute up to 100 authorized commands sequentially; requires MA2_ALLOW_WRITE=1 and matching Show.

Not transactional. Stops at first failure; prior commands may already be applied. Do not retry after a timeout without querying state. User scope still governs every command.

Inputs: commands (required), expected_show (required), target. Returns: object

ma2_exportB

Export a local native object to unique XML and return a timestamp-independent fingerprint.

Inputs: object (required), target. Returns: object

ma2_listB
Read-onlyIdempotent

List a native object/range, e.g. Executor 3.1 Thru 3.8 or Root 10.6.3; no command chains.

Inputs: object (required), target. Returns: object

ma2_statusA
Read-onlyIdempotent

Inspect one verified runtime: target is onpc or ma3d. Does not change the Show.

Inputs: target. Returns: object

ma3d_captureA

Save the uniquely identified visible local MA3D window as PNG, without UI input.

Windows only. Read the returned image to inspect the camera and beams. Does not start playback, select Front, or certify visual acceptance. Minimized/blank/ambiguous windows fail.

Inputs: window_title.

ma3d_transformA
Destructive

Set x/y/z (metres), rx/ry/rz (degrees), or camera fov (radians), and return before/after List.

Requires an inspected scene Root address or Camera number. Installation orientation is NOT programmed Pan/Tilt. MA3D edits can synchronize into onPC. Use target=onpc if its shared scene is the intended authority. Requires write gate and expected Show; no visual pass is implied.

Inputs: object (required), values (required), expected_show (required), target. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have a clearly distinct action (list, execute, export, backup, transform, capture). The one weak pair is ma2_connections vs ma2_status, since both return runtime identity and Show/session state and differ mainly by whether a connection is established — an agent could reasonably pick the wrong one.

    Naming Consistency4/5

    Names are uniformly snake_case with a useful ma2_/ma3d_ subsystem prefix, making scope obvious at a glance. Minor deviation: some are verbs (list, execute, export, backup, transform, capture) while others are nouns (connections, status).

    Tool Count5/5

    Eight tools is well-scoped for a console/visualizer control surface: connection, inspection, listing, command execution, export, backup, 3D transform, and capture. Each earns its place with no filler.

    Completeness4/5

    Core lifecycle is covered: connect, inspect, read state, write commands, export, back up, manipulate 3D scene, and capture visuals. Gaps remain around disconnect, cancelling/aborting a hung execute, and reading command feedback or history, which agents may need after partial failures.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      An MCP server that lets AI assistants control grandMA2 lighting consoles via Telnet, exposing 41 high-level tools for cue management, fixture control, preset management, executor control, macro editing, appearance assignment, bulk operations, console state queries, show file management, read-back verification, and music show workflows.
      100
      20
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables driving TouchDesigner from any MCP client during live rendering, with safe never-overwrite saves, GPU health measurement, and 67 tools for node, parameter, data, and timeline control.
      67
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to control grandMA3 consoles through official OSC /cmd commands, with an admin UI for IP scanning, object/action permissions, chat integration, and MCP stdio access.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients such as Claude Code or Claude Desktop to control grandMA3 onPC by executing command-line commands, running Lua, reading show data like sequences, cues, executors, patch and pools, driving playback and faders, and looking things up in the manual. It works through a Lua bridge plugin inside onPC, falling back to OSC for write-only commands when the bridge is unavailable.
      75
      9
      MIT