Beyond MCP

An MCP server for Pangolin BEYOND laser software. Exposes 117 tools across 20 categories covering show control, cue management, zone configuration, geometric correction, live parameter control, effects, projector alignment, safety limiters, and more — all via OSC.

Built for live production. Pairs with grandMA2 MCP, Resolume MCP, MADRIX MCP, and Companion MCP for full AI-driven show control.

Why this exists

Pangolin BEYOND is the industry-standard laser show software, but programming laser cues, adjusting zones, and tuning live parameters is entirely manual. An operator clicks through the BEYOND UI, one parameter at a time, across dozens of zones and cues.

This MCP server lets an AI assistant control BEYOND over OSC. It can trigger cues, adjust master brightness, mute zones, set BPM, control projector alignment, apply geometric corrections, manage safety limiters, and control live parameters — all from a single conversation. Combined with MA2 Agent, Resolume MCP, and Companion MCP, an AI assistant can orchestrate the entire show control stack.

Quick start

git clone https://github.com/drohi-r/beyond-mcp && cd beyond-mcp
uv sync
uv run python -m beyond_mcp

Make sure BEYOND is running with OSC input enabled (configurable via BEYOND_OSC_PORT, defaults to 12000).

For remote control:

• use LAN or WireGuard, not the public internet
• allow UDP to BEYOND_OSC_PORT
• set BEYOND_HOST to the remote machine and include it in BEYOND_ALLOWED_HOSTS

Live-Validated Build Notes

This repo has been exercised against a real BEYOND instance over LAN, not only mocked unit tests.

Live-confirmed tools on the validated build:

• display_popup
• set_bpm
• select_next_page / select_prev_page
• select_next_tab / select_prev_tab
• start_cue_by_name / stop_cue_by_name
• set_master_brightness

Build-specific notes:

• load_cue sent cleanly but did not produce an obvious visible state change in the tested workspace.
• display_preview("main", ...) sent cleanly, but main did not appear to be the correct preview identifier for the validated BEYOND setup.

Full notes: docs/live-validation.md

See also:

• docs/mcp-config-examples.md
• docs/operator-workflows.md

Configuration

Variable	Default	Description
BEYOND_HOST	127.0.0.1	BEYOND instance IP
BEYOND_OSC_PORT	12000	OSC receive port
BEYOND_ALLOWED_HOSTS	127.0.0.1,localhost,::1	Comma-separated allowlist for target hosts. Set * to allow any.
BEYOND_SAFETY_PROFILE	lab	Safety preset: lab, show-safe, or read-only
BEYOND_READ_ONLY	0	Set to 1 for read-only mode (blocks all write operations)
BEYOND_CONFIRM_DESTRUCTIVE	0	Set to 1 to require confirm=true on destructive operations (blackout, stop_all, etc.)
BEYOND_TRANSPORT	stdio	MCP transport (stdio, sse, streamable-http)

Architecture

graph TD
    A["Beyond MCP Server<br/><code>beyond_mcp</code><br/>117 tools · 20 categories · safety gate"] --> B
    B["OSC Client<br/>UDP fire-and-forget"] --> C
    C["Pangolin BEYOND<br/>OSC input on port 12000"]

    D["Safety Profiles<br/>lab · show-safe · read-only"] -.-> A
    E["Preview Engine<br/>Dry-run OSC inspection"] -.-> A
    F["Bundle Support<br/>Atomic multi-message delivery"] -.-> B

    style A fill:#1a1a2e,stroke:#F59E0B,color:#fff
    style B fill:#1a1a2e,stroke:#F59E0B,color:#fff
    style C fill:#1a1a2e,stroke:#0f3460,color:#fff
    style D fill:#0f3460,stroke:#0f3460,color:#fff
    style E fill:#0f3460,stroke:#0f3460,color:#fff
    style F fill:#0f3460,stroke:#0f3460,color:#fff

Safety profiles

BEYOND_SAFETY_PROFILE gives you a sane starting point without having to remember multiple flags:

• lab
  • read_only = false
  • confirm_destructive = false
• show-safe
  • read_only = false
  • confirm_destructive = true
• read-only
  • read_only = true
  • confirm_destructive = true

Explicit environment flags still win if you need to override the profile:

BEYOND_SAFETY_PROFILE=show-safe \
BEYOND_CONFIRM_DESTRUCTIVE=0 \
uv run python -m beyond_mcp

Tools

System

Tool	What it does
get_server_config	Return current MCP server configuration and safety settings
health_check	Check if the BEYOND target is reachable and report resolved socket details
send_osc_raw	Send a raw OSC message for any address not wrapped by a named tool
send_osc_bundle	Send multiple OSC messages as an atomic bundle
preview_osc	Preview an OSC message without sending it (dry-run inspection)
preview_osc_bundle	Preview an OSC bundle without sending it

Master Controls

Tool	What it does
set_master_brightness	Set master brightness (0-100)
blackout	Activate blackout — disable all laser output
enable_laser_output	Enable laser output (undo blackout)
disable_laser_output	Disable laser output
master_pause	Pause or unpause master playback
master_pause_time	Pause or unpause master playback with time sync
set_master_speed	Set master playback speed (0-10)
stop_all_now	Stop all playback immediately
stop_all_sync	Stop all playback with synchronization fade
stop_all_async	Stop all playback asynchronously with fade

BPM / Beat

Tool	What it does
set_bpm	Set the BPM tempo value (1-999)
set_bpm_delta	Adjust BPM by a delta value
beat_tap	Register a beat tap for tempo detection
beat_resync	Resynchronize beat timing
beat_source_timer	Set beat source to internal timer
beat_source_audio	Set beat source to audio input
beat_source_manual	Set beat source to manual tap

Cue Mode

Tool	What it does
set_cue_mode_single	Set cue mode to Single Cue (one active cue at a time)
set_cue_mode_one_per	Set cue mode to One Per (one per group)
set_cue_mode_multi	Set cue mode to Multi Cue (multiple simultaneous cues)

Click Behavior

Tool	What it does
click_mode_select	Set click behavior to Select mode
click_mode_toggle	Set click behavior to Toggle mode
click_mode_restart	Set click behavior to Restart mode
click_mode_flash	Set click behavior to Flash mode
click_mode_solo_flash	Set click behavior to Solo Flash mode
click_mode_live	Set click behavior to Live mode
set_click_scroll	Set a click-scroll parameter (zoom, size, fade, vpoints, scanrate, color, anispeed, red, green, blue, alpha)

Transitions

Tool	What it does
set_transition_type	Set the transition type by index
set_master_transition_index	Set the master transition effect index
set_master_transition_time	Set the master transition time in seconds

Cue / Cell Control

Tool	What it does
select_cue	Select a cue by name
start_cue_by_name	Start a cue by name
stop_cue_by_name	Stop a cue by name
stop_cue_now	Stop a specific cue immediately
stop_cue_sync	Stop a specific cue with synchronization fade
cue_down	Navigate cue selection downward
cue_up	Navigate cue selection upward
pause_cue	Pause or unpause a cue
restart_cue	Restart a cue from the beginning
focus_cell	Focus on a cell by page and cue coordinates
focus_cell_index	Focus on a cell by linear index
start_cell	Start the currently focused cell
restart_cell	Restart the currently focused cell
stop_cell	Stop the currently focused cell
shift_focus	Shift cell focus by direction offset
move_focus	Move cell focus by delta X and Y
unselect_all_cues	Deselect all active cues

Workspace

Tool	What it does
load_cue	Load a cue by name without starting it
load_workspace	Load a workspace by name

Page / Tab / Category Navigation

Tool	What it does
select_page	Select a page by index
select_next_page	Navigate to the next page
select_prev_page	Navigate to the previous page
select_tab	Select a tab by index
select_tab_by_name	Select a tab by name
select_next_tab	Navigate to the next tab
select_prev_tab	Navigate to the previous tab
select_all_categories	Select all content categories
select_category	Select a content category by index
select_category_by_name	Select a content category by name
select_next_category	Navigate to the next content category
select_prev_category	Navigate to the previous content category

Grid Management

Tool	What it does
set_grid_size	Set the cue grid dimensions
select_grid	Select a grid by index

Zone Control

Tool	What it does
mute_zone	Mute a projection zone by index
unmute_zone	Unmute a projection zone by index
toggle_mute_zone	Toggle mute state for a projection zone
unmute_all_zones	Unmute all projection zones
stop_zone	Stop output on a zone with optional fade time
stop_zone_by_name	Stop output on a zone by name
stop_zones_of_projector	Stop all zones assigned to a projector
stop_projector_by_name	Stop all zones of a projector by name
select_zone	Select a projection zone
select_zone_by_name	Select a projection zone by name
unselect_zone	Unselect a projection zone
unselect_all_zones	Unselect all projection zones
toggle_select_zone	Toggle selection state for a projection zone
store_zone_selection	Store the current zone selection for later recall
restore_zone_selection	Restore a previously stored zone selection
set_zone_brightness	Set brightness for a specific zone (0-100)

Live Control Parameters (Master scope)

Tool	What it does
set_master_size	Set master size X and Y (-400 to 400)
set_master_position	Set master position X and Y (-32768 to 32768)
set_master_rotation	Set master rotation angles X, Y, Z (-2880 to 2880)
set_master_rotation_speed	Set master continuous rotation speed X, Y, Z (-1440 to 1440)
set_master_color	Set master color RGB (0-255 each)
set_master_alpha	Set master alpha/opacity (0-255)
set_master_zoom	Set master zoom (0-100)
set_master_scan_rate	Set master scan rate (10-200)
set_master_visible_points	Set master visible points percentage (0-100)
set_master_color_slider	Set master color slider (0-255)
set_master_animation_speed	Set master animation speed (0-400)

Live Control: Effects (Master scope)

Tool	What it does
set_master_effect	Set an effect on a master FX slot (slot 1-4, effect_index -1..47)
set_master_effect_action	Set the action/intensity of a master FX slot (slot 1-4, value 0-100)

Projector Control

Tool	What it does
set_projector_size	Set projector output size X and Y (-100 to 100)
set_projector_position	Set projector output position X and Y (-100 to 100)
projector_swap_xy	Toggle projector X/Y axis swap
projector_invert_x	Toggle projector X-axis inversion
projector_invert_y	Toggle projector Y-axis inversion

Zone Setup / Geometric Correction

Tool	What it does
zone_setup_select	Select a zone for geometric setup
zone_setup_next_zone	Navigate to the next zone in setup
zone_setup_prev_zone	Navigate to the previous zone in setup
zone_setup_select_param	Select a geometric parameter by index for editing
zone_setup_next_param	Navigate to the next geometric parameter
zone_setup_prev_param	Navigate to the previous geometric parameter
zone_setup_set	Set a zone geometric correction parameter (xsize, ysize, xposition, yposition, zrotation, keystone, pincussion, bow, shear, and more)

Safety Limiter

Tool	What it does
set_limiter	Set a safety limiter (profile, per_zone, per_grid, flash, hold, beam, dmx, show)

Display

Tool	What it does
display_popup	Display a popup message in BEYOND
display_preview	Show or hide a named preview window

DMX / Channel Output

Tool	What it does
channel_out	Send a value to a BEYOND output channel

Control Scope

Tool	What it does
set_control_scope	Set the live control target scope (master, cue, zone, track, projector, smart)

Virtual LJ

Tool	What it does
virtual_lj	Enable or disable Virtual LJ mode
virtual_lj_fx	Trigger a Virtual LJ effect

Claude Desktop

{
  "mcpServers": {
    "beyond": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/beyond-mcp", "python", "-m", "beyond_mcp"],
      "env": {
        "BEYOND_HOST": "127.0.0.1",
        "BEYOND_OSC_PORT": "12000"
      }
    }
  }
}

VS Code / Cursor

{
  "servers": {
    "beyond": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/beyond-mcp", "python", "-m", "beyond_mcp"],
      "env": {
        "BEYOND_HOST": "127.0.0.1",
        "BEYOND_OSC_PORT": "12000"
      }
    }
  }
}

More examples, including LAN-targeted setups: docs/mcp-config-examples.md

Codex

Create a codex.json MCP config file:

{
  "mcpServers": {
    "beyond": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/beyond-mcp", "python", "-m", "beyond_mcp"],
      "env": {
        "BEYOND_HOST": "127.0.0.1",
        "BEYOND_OSC_PORT": "12000"
      }
    }
  }
}

Then run Codex with:

codex --mcp-config codex.json

Production safety

This server is designed for live show environments where accidental commands can disrupt a running laser show. All 117 tools include full parameter validation.

• UDP fire-and-forget -- BEYOND OSC control uses UDP, meaning commands are sent without acknowledgement. There is no rollback. Every tool call is a real action on the laser system.
• Host allowlisting -- only 127.0.0.1, localhost, and ::1 are permitted by default. Add LAN hosts explicitly via BEYOND_ALLOWED_HOSTS. Set * to allow any host.
• Read-only mode -- set BEYOND_READ_ONLY=1 to block all write operations. Only get_server_config, health_check, preview_osc, and preview_osc_bundle remain available.
• Confirm-destructive gating -- set BEYOND_CONFIRM_DESTRUCTIVE=1 to require confirm=true on destructive operations, including raw/bundle sends of destructive OSC addresses and disruptive named tools like load_workspace, stop_zone, and stop_projector_by_name.
• Health check -- health_check verifies BEYOND target reachability via DNS resolution and UDP socket test and reports the resolved address family/socket target.
• OSC bundle support -- send_osc_bundle sends multiple OSC messages as an atomic bundle, ensuring all-or-nothing delivery for coordinated multi-parameter changes.
• Preview before send -- preview_osc and preview_osc_bundle return the exact packet details without transmitting anything. Use them before high-risk live operations.
• Input validation -- all 117 tools with documented parameter ranges enforce bounds before any OSC message is built. Brightness, zoom, scan rate, size, position, rotation, color, BPM, speed, fade times, effect slots, limiter types, geometric correction parameters, and non-negative indexes are all range-checked. Invalid inputs return structured JSON errors, never raw exceptions.
• Error isolation -- all tools are wrapped in _handle_errors. OSC send failures, JSON parse errors, validation failures, and unexpected exceptions return {"ok": false, "error": "...", "blocked": true} instead of crashing the MCP session.
• Transport validation -- only stdio, sse, and streamable-http transports are accepted. Invalid transport values raise immediately at startup.
• Port validation -- BEYOND_OSC_PORT is validated as an integer in the 1-65535 range at config load time.
• Raw escape hatch -- send_osc_raw allows any OSC address for coverage beyond the named tools, but requires explicit JSON array input and validates structure before sending.

Suggested Operator Flow

For first use on a new BEYOND machine:

1. get_server_config
2. health_check
3. display_popup
4. set_bpm
5. page/tab navigation
6. non-critical cue start/stop
7. live parameter tests like master brightness

More practical sequences: docs/operator-workflows.md

Development

uv sync
uv run python -m pytest -v

License

Apache 2.0