LightBurn MCP

Talk to your LightBurn project from Claude, Cursor, ChatGPT and any other MCP client.

Read the open project · explain and sanity-check cut settings · change them by sentence · apply materials from your library · drop AI-generated SVGs straight onto the workspace

LightBurn 2.2 ships a local REST API. This project wraps it as a Model Context Protocol server, so an AI assistant can work with the LightBurn window you have open — on your machine, with no account and no cloud in between.

You:     Layer C02 is 10 mm/s at 80 %. Is that plausible for 3 mm poplar on my 40 W CO2?
Claude:  (reads get_project, get_units, get_cut 2) …that will likely char the edges.
         Want me to set 15 mm/s / 65 % and 2 passes? Review it in LightBurn before you run.
You:     Yes.
Claude:  (update_cut) Done – speed 15, max_power 65, num_passes 2.
         Review these settings in LightBurn before running the job.

Table of contents

• What it can do

• What it cannot do

• Quick start

• Connect your client

• ChatGPT and other URL-based clients

• Example prompts

• Tools

• How it works

• CLI reference

• Troubleshooting

• Safety

• Development

• License

Related MCP server: Obsidian MCP Server

What it can do

Works with LightBurn (port 19520) and MillMage (port 19521, untested so far).

What it cannot do

The LightBurn API deliberately has no machine control: no start, stop, pause, frame, jog or home. There is no shape editing, no layer assignment, no save, no export. Changing cut settings edits the project only — you review it in LightBurn and run the job. Every write tool says so in its result. Read SAFETY.md once.

Quick start

You need: LightBurn 2.2.00 or newer running on this computer, and Node.js 20+ (the LTS installer is fine). The package is published on npm as lightburn-mcp.

Start LightBurn, open a terminal (PowerShell on Windows, Terminal on macOS) and run:

npx lightburn-mcp setup

That uses the released package from npm. To run the latest commit on main instead: npx github:DerChris2011/Lightburn_MCP setup.

Setup walks you through four steps:

1. Application – lightburn (default) or millmage.

2. Capabilities – what the assistant may do. Default is all four:

   Capability	Grants
   state	read machine and job state
   project	read project data — includes the camera overlay image
   upload	import files into the project
   project_write	change cut settings

3. Pairing – LightBurn pops up a consent dialog naming LightBurn MCP and the capabilities. Approve it within 30 seconds. The secret is stored in your user profile and never leaves your machine.

4. Clients – pick the MCP clients to configure. Their config files are updated with a backup kept next to them. Restart the client and you're done.

The first npx run downloads the package from npm (a few seconds; the GitHub variant clones and builds it instead, about a minute). After that your clients start the server directly, in well under a second.

Check anytime:

npx lightburn-mcp status

Product:      lightburn
Host:         localhost:19520
Reachable:    yes
Paired:       yes (secret source: file)
Capabilities: state, project, upload, project_write

Connect your client

setup does this for you. To (re)do a single client:

npx lightburn-mcp config <client> --write

Full JSON for every client, Windows and macOS, is in docs/clients.md.

ChatGPT and other URL-based clients

ChatGPT adds MCP servers as connectors and only accepts a public HTTPS URL — it cannot start a local process and rejects localhost. For that the server has an HTTP mode that always requires an access token:

npx lightburn-mcp --http
# LightBurn MCP listening on http://127.0.0.1:3917/mcp
# Token required: header "Authorization: Bearer <token>" or URL http://127.0.0.1:3917/mcp/<token>

Clients that can send headers use the bearer header (Claude Code: claude mcp add --transport http lightburn http://127.0.0.1:3917/mcp --header "Authorization: Bearer <token>"). ChatGPT can't, so put the token in the URL and a tunnel in front:

ngrok http 3917            # or: cloudflared tunnel --url http://127.0.0.1:3917

Add https://<your-tunnel-host>/mcp/<token> as a custom connector in ChatGPT (Settings → Connectors, Developer Mode, eligible plans only). Show the token with lightburn-mcp token, rotate it with lightburn-mcp token --rotate.

⚠️ The tunnel URL is a secret. Anyone who has it can read your project and change cut settings. Stop the tunnel when you're done. LightBurn Software does not endorse remote machine operation — see SAFETY.md.

Example prompts

• "Summarise my current LightBurn project: layers in use and their settings."

• "Compare every used layer against my material library and tell me which ones differ."

• "Set every layer that is in use to 2 passes."

• "Apply the Plywood 3 mm entry from my library to layer 2."

• "Create a 60 mm circle with the text Workshop inside as SVG and import it at 50,50, top-left origin, grouped."

• "Is the machine connected, and what are the current speed and power overrides?"

• "Show me the camera overlay and tell me where the material is."

Tools

Values follow LightBurn's display units (get_units). Every write tool ends with "Review these settings in LightBurn before running the job."

Built-in LightBurn knowledge

Tools alone make an assistant guess. The server therefore also ships what it should know, so answers are grounded in how LightBurn and your laser actually work:

• Server instructions every client receives on connect: read units first, use the cuts' in_use, read a cut before changing it, set override_frequency with frequency, treat Ruida's connected: false as normal, always end a change with the review reminder.

• Six knowledge resources (lightburn://knowledge/…) the assistant can read on demand: API rules and pitfalls · cut settings explained (modes, sub-layers, min/max power, kerf, interval/DPI, dither modes) · laser types (diode, CO2, Q-switched fiber, MOPA fiber with pulse width, UV, dual-source) · galvo specifics (frequency, timing constants, jump settings, wobble, deep engraving, annealing, colour marking) · gantry specifics (power ramping, air assist, PPI, lead-in, cut-through, overcut) · workflows (summarise, review, change, apply material, SVG import with mm units and the colour-to-layer palette).

• Three prompts your client can offer as one-click actions: summarize_project, review_cut_settings (with material and goal), prepare_import (description and position).

The knowledge gives orders of magnitude for plausibility checks, not recipes. It tells the assistant to prefer your material library and existing layers over any table, and never to present a value as correct for your machine.

How it works

flowchart LR
    subgraph Your computer
        Client["MCP client<br/>(Claude Desktop, Cursor, …)"]
        Server["lightburn-mcp<br/>stdio or HTTP"]
        LB["LightBurn 2.2<br/>REST API :19520"]
        Client -- "MCP (stdio)" --> Server
        Server -- "HTTP + HMAC bearer token" --> LB
        LB -- "consent dialog once" --> You((You))
    end
    ChatGPT["ChatGPT / URL clients"] -- "HTTPS tunnel + token" --> Server

• Pairing calls POST /api/connect; LightBurn shows the consent dialog and returns a secret. The server stores it in %APPDATA%\lightburn-mcp\config.json (Windows) or ~/Library/Application Support/lightburn-mcp/config.json (macOS).

• Every request carries hex(HMAC-SHA256(secret, floor(unix_time / 60))) as a bearer token, exactly as the API specifies. A rejected token is retried once, then the tool asks you to re-pair.

• Imports open LightBurn's event stream before sending the file, so the file_imported result is reported back instead of a bare "accepted".

• Nothing is cached: every tool call reads live from LightBurn.

Environment variables override the stored config for advanced setups — for example a server on another machine using a secret copied from Manage API Security in LightBurn: LIGHTBURN_SECRET, LIGHTBURN_HOST, LIGHTBURN_PRODUCT, LIGHTBURN_MCP_CONFIG_DIR.

CLI reference

lightburn-mcp                      Start the MCP server on stdio
lightburn-mcp --http [--port N] [--host H] [--token T]
                                   Start over Streamable HTTP (token always required)
lightburn-mcp setup                Interactive: pair + configure clients
lightburn-mcp pair [--capabilities state,project,upload,project_write]
lightburn-mcp status               Pairing state, reachability
lightburn-mcp config <client> [--write]
lightburn-mcp token [--rotate]     Show or rotate the HTTP access token
lightburn-mcp --version | --help

(npx lightburn-mcp <command> works without installing; npm install -g lightburn-mcp gives you the lightburn-mcp command.)

Troubleshooting

Safety

Cut settings control laser power, speed and passes. Review every setting the assistant touched in LightBurn before you press Start. The API cannot start or stop a machine, this server adds no such ability, and it is not a safety system. LightBurn Software does not endorse remote or unattended operation. Details in SAFETY.md.

Development

git clone https://github.com/DerChris2011/Lightburn_MCP.git
cd Lightburn_MCP
npm install
npm test            # tests against an in-process mock of the LightBurn API
node scripts/mcpcall.mjs '[["get_status"],["get_cut",{"index":0}]]'   # call tools of the built server from the shell
npm run build
node dist/index.js --help

TypeScript, @modelcontextprotocol/sdk, zod, express; tests with Vitest. CI runs on Windows and macOS. The design document and implementation plan live in docs/superpowers/. Issues and pull requests are welcome.

License

MIT © DerChris2011. The LightBurn / MillMage API is governed by LightBurn Software's API EULA. This project is not affiliated with or endorsed by LightBurn Software.