LightBurn MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| LIGHTBURN_HOST | No | Host of the LightBurn (or MillMage) REST API to connect to, e.g. the IP of the machine running LightBurn when running the server on a different machine. Overrides the stored config. | |
| LIGHTBURN_SECRET | No | Pairing secret, needed when running the server on another machine: pair on the LightBurn machine, enable Settings → Extensions → Allow API Access From Network, copy the secret via Manage API Security → Show Secret…, then start the server with LIGHTBURN_SECRET=… LIGHTBURN_HOST=<ip>. Overrides the secret stored in the config file. | |
| LIGHTBURN_PRODUCT | No | The application to talk to: lightburn (default, port 19520) or millmage (port 19521). Overrides the stored config. | |
| LIGHTBURN_MCP_CONFIG_DIR | No | Directory where the stored configuration (including the pairing secret) lives. Overrides the default location %APPDATA%\lightburn-mcp\config.json (Windows) or ~/Library/Application Support/lightburn-mcp/config.json (macOS). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| pairA | Pairs this server with the running LightBurn / MillMage on this machine. LightBurn shows a consent dialog naming the application and the requested capabilities; the user must approve it within 30 seconds. The secret is stored in the per-user config and never returned. Capabilities are fixed for the life of the pairing; call pair again to change them. Note that "project" includes the camera overlay image. |
| connection_infoA | Shows how this server is configured: product, host, port, whether it is paired, granted capabilities, and whether LightBurn is reachable right now. Never reveals the secret. |
| get_statusA | Requires capability "state". Connection status and device capabilities of the selected device profile (device_name, connected, supports_z, supports_overrides). |
| get_positionA | Requires capability "state". Current machine and workpiece coordinates, always in mm. Axes the controller does not report are omitted. |
| get_unitsA | Requires capability "state". The user's display units: |
| get_jog_settingsA | Requires capability "state". Current jog distance and speed settings in display units. |
| get_saved_positionsB | Requires capability "state". Saved positions from the device profile. |
| get_state_snapshotA | Requires capability "state". Latest state snapshot in one call: position, job state and progress, speed/power overrides, aux state, connection and jog settings. On Ruida controllers job.state is always idle and progress is never reported. |
| get_projectA | Requires capability "project". Metadata of the open project: filename, modified flag, shape count, display units, workspace size in mm and the selected device including laser source capabilities (device.laser.controller tells which controller is attached). |
| get_layersA | Requires capability "project". All 32 layer definitions (index, name, color as #RRGGBB, type, hidden, in_use, shape_count) and the active layer index. By default only layers in use are returned. |
| get_cutsA | Requires capability "project". Cut settings of the project. LightBurn returns a fixed list: 30 cut layers, 2 tool layers, 1 internal entry, then 30 image cuts; MillMage returns its operation list. Each entry's |
| get_cutA | Requires capability "project". One cut entry with every field, by the flat index from get_cuts. For LightBurn normal cuts, params contains exactly one machine block (params.galvo or params.gantry) matching the entry's profile. |
| get_material_libraryA | Requires capability "project". The currently loaded material library (LightBurn: flat entries with material, thickness, description, guid and a full cut setting; MillMage: operations library trees). |
| get_camera_overlay_metadataA | Requires capability "project". Size, workspace placement (mm) and a revision token of the camera overlay, without transferring the image. LightBurn only; 404 when no overlay is loaded. |
| get_camera_overlayA | Requires capability "project". The camera overlay currently drawn on the workspace as a PNG image, plus its metadata. Returns what LightBurn already has in memory; it never triggers a new capture. LightBurn only. |
| update_cutA | Requires capability "project_write". Partial update of one cut entry (LightBurn layer or MillMage operation) by its flat index from get_cuts. Only the fields in |
| apply_material_to_cutA | Requires capabilities "project" and "project_write". Copies a material library entry (mode and base-layer params, plus sub-layer values for sub-layers the target cut already has) onto a cut entry. Select the entry by entry_guid, or by material name (case-insensitive) and optional thickness. Refuses when several entries match, when the entry has more sub-layers than the target, or when kinds differ. A machine block (galvo/gantry) that does not match the target profile is skipped and reported. |
| upload_fileA | Requires capability "upload" (plus "state" for import confirmation). Imports a file into the CURRENT project (merge), like File > Import. Supported: .svg, .dxf, .ai, .pdf, .lbrn/.lbrn2, .png/.jpg/.bmp and other formats LightBurn can import. Send a local file via path, or generated content via content (text such as SVG) or content_base64. Optionally anchor the import at workspace coordinates x/y in mm (workpiece origin) with origin naming which point of the bounding box sits at the anchor (default center); without x/y it lands at the current view center. Waits up to wait_seconds for LightBurn's file_imported event and reports the outcome. |
| open_fileA | Requires capability "upload" (plus "state" for confirmation). REPLACES the current project with the file, like File > Open; LightBurn prompts the user to save unsaved changes first. Send a local file via path, or content / content_base64 with a filename. LightBurn confirms success reliably only for native projects (.lbrn, .lbrn2, .mage); for other formats this tool reads the project afterwards and reports it as opened_unconfirmed. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| summarize_project | Machine, project size and every layer in use with its settings, in the user's units. |
| review_cut_settings | Checks every used layer against the laser type and (optionally) the stated material; suggests changes but does not apply them. |
| prepare_import | Builds an SVG in millimetres from a description and imports it into the open project at a position. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| api-rules | Units, index vs layer_index, in_use, profile/galvo/gantry blocks, override_frequency, Ruida quirks, write semantics, import confirmation. Read before interpreting or changing values. |
| cut-settings | What every cut field means: modes, sub-layers, min/max power, speed, passes, kerf, interval/DPI, scan options, tabs, perforation, image dither modes, frequency. |
| laser-types | How to identify the machine from get_project, which fields apply to each laser type, what the numbers roughly mean, and what each type can and cannot do. Orders of magnitude only. |
| galvo | Frequency, pulse width, line interval, the params.galvo block (timing constants, jump settings, wobble), global_passes, deep engraving, annealing, colour marking. |
| gantry | Min/max power ramping, the params.gantry block (air assist, PPI, cut-through, lead in/out, dot mode, overcut), CO2 and diode specifics, typical layer shapes. |
| workflows | Step sequences for summarising a project, reviewing settings, changing settings, applying library materials, importing SVGs (units, colour→layer mapping, placement), and handling errors. |
TDQS
Scored across 19 tools
Tools target distinct resource+action pairs: get_cuts vs get_cut (list vs single), get_position vs get_jog_settings vs get_saved_positions, and get_camera_overlay vs its metadata variant are clearly delineated. Minor overlap exists between the state readers (get_position, get_units, get_jog_settings are all subsumed by get_state_snapshot) and among get_status/connection_info/get_state_snapshot, but descriptions disambiguate them.
Strong get_/update_/apply_/upload_/open_ verb_noun pattern throughout, with clean noun suffixes distinguishing variants (_metadata, _snapshot, _settings). The bare 'pair' and noun-phrase 'connection_info' are minor deviations but still readable and unambiguous.
19 tools is slightly above the ideal range but each earns its place in a genuinely layered domain (state reads, cut editing, material library, camera overlay, file import, pairing). No obvious redundant bloat; the granular state getters are defensible as lightweight alternatives to the full snapshot.
Cut handling has read and update but no create/delete or add-layer operation, and there is no jog/move command or job control (start/pause/stop) despite get_jog_settings and job-state reporting — notable gaps for a laser-control surface. The read/derive side and file/camera operations are otherwise well covered.