PanelWorks MCP Server
Connects PanelWorks forms to MQTT brokers and devices. Controls can subscribe properties to topics, publish events to topics, mirror form state, and use MQTT connection settings such as TLS and credentials. MCP tools expose MQTT status and publishing.
Integrates with n8n through HTTP webhooks, letting n8n workflows act as PanelWorks event procedures. Form events can call webhook URLs, and webhook replies can drive form changes; status tools report webhook call counts and errors.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
PanelWorks
Draw a form in JSON, write Object_Event procedures in Python, and run it as a
real Tkinter desktop window. Every object is live-addressable, by agents over
MCP (Claude can read and set properties, call methods, wait for events, even
draw new controls while the app runs), by devices over MQTT (subscribe
properties to topics, publish on events, mirror the whole form) and by
automations over webhooks (an n8n workflow can be an event procedure).

Recorded session: an MCP client (as Claude would) adds an E-STOP button to a
running panel, starts the pump, waits for the E-STOP click, then stops it.
Script: tests/record_demo.py.
The programming model is the classic RAD one: a form, named controls, properties,
methods and events (cmdStart_Click), as popularised by Visual Basic and Delphi.
PanelWorks is an independent project and is not affiliated with Microsoft, nor
with the HoloViz "Panel" dashboard library.
examples/pumppanel.json <- a form: objects + properties
examples/pumppanel.py <- its event procedures
examples/cistern_mqtt.* <- a no-code panel driven entirely by MQTT subscriptions
examples/n8n_demo.* <- a panel whose event procedures live in n8n
examples/hvac_console.* <- read-only HVAC console for real ESP32 devices over MQTT/TLS
examples/n8n/ <- the matching n8n workflow, ready to import
tests/fake_esp32.py <- simulated cistern node to test it against
panelworks/runtime.py <- controls, Form, event dispatch, thread bridge
panelworks/mcp_bridge.py <- MCP server, single-instance lock and relay
panelworks/mqtt.py <- MQTT control, subscribe / publish / mirror
panelworks/webhooks.py <- HTTP webhooks (n8n): events out, replies drive the form
panelworks/cli.py <- the `panelworks` commandInstall
Python 3.10+ with Tkinter (included in the python.org Windows/macOS installers;
on Debian/Ubuntu sudo apt install python3-tk). From the project folder:
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[mqtt]" # Windows
.venv/bin/python -m pip install -e ".[mqtt]" # macOS / LinuxThat installs a panelworks command into the venv (-e = editable, so changes to
the source take effect without reinstalling). Leave off [mqtt] to skip paho-mqtt.
Works with mcp 2.x (tested 2.3.0) and falls back to the 1.x FastMCP API.
MQTT needs paho-mqtt 2.x (tested 2.2.0); without it, forms still run, minus MQTT.
Related MCP server: Desktop Pilot MCP
Run
panelworks examples/pumppanel.json # window + MCP at http://127.0.0.1:8765/mcp
panelworks examples/pumppanel.json --mcp stdio # for Claude Desktop / Claude Code
panelworks examples/pumppanel.json --mcp none # just the desktop app
python -m panelworks ... # same thing, if the command isn't on PATHHook it to Claude Desktop
Add a server to claude_desktop_config.json. Let the app find the file for you,
because its location varies by install. In Claude Desktop, open Settings and type
"developer" in the search box (it isn't in the menu list), choose Extensions,
and use its config button to show the file. Open it in Notepad
(right-click → Open with → Notepad).
Typical locations: %APPDATA%\Claude\ or %LOCALAPPDATA%\Claude-Data\... on
Windows, and ~/Library/Application Support/Claude/ on macOS.
Quit Claude Desktop from the tray icon (or Task Manager) before editing, and
restart it afterwards. Closing the window only hides it, and the app rewrites
this file while running. If the server doesn't show up, that's the usual cause. If the file already has content, add mcpServers as a new top-level
key, and watch the commas:
{
"mcpServers": {
"pumppanel": {
"command": "C:/dev/panelworks/.venv/Scripts/panelworks.exe",
"args": ["C:/dev/panelworks/examples/pumppanel.json", "--mcp", "stdio"]
}
}
}Restart Claude Desktop; the panel window opens and Claude can ask it things like "press Start", "what's the cistern level?", or "add a Stop-All button under Start".
Claude Code over HTTP: start with the default --mcp http, then
claude mcp add --transport http pumppanel http://127.0.0.1:8765/mcp.
The form file
{
"name": "PumpPanel",
"caption": "Cistern Pump Panel",
"width": 420, "height": 300,
"code": "pumppanel.py",
"objects": {
"cmdStart": {"type": "CommandButton", "Caption": "Start",
"Left": 15, "Top": 145, "Width": 90, "Height": 30},
"tmrSim": {"type": "Timer", "Interval": 500, "Enabled": true}
}
}Property names follow the classic RAD conventions (Caption, Text, Value, Left, Top). Positions are pixels from the top-left of the form.
Event procedures
def cmdStart_Click(f): # f is the form ("Me")
f.shpPump.FillColor = "lime green"
f.cmdStop.Enabled = True
f.lstLog.AddItem("Pump ON")
def txtSetpoint_KeyPress(f, key_ascii):
...
def tmrSim_Timer(f):
f.barLevel.Value += 1Events are held until the form finishes building, then Form_Load fires.
Setting TextBox.Text fires Change, and setting CheckBox.Value /
OptionButton.Value fires Click, as in classic VB. A handler that raises an exception prints
a traceback and logs the error in the event log; the app keeps running.
Controls
Type | Key properties | Methods | Events |
Label | Caption, Alignment | Click, DblClick | |
CommandButton | Caption | Click (press it) | Click, GotFocus, LostFocus |
TextBox | Text, Locked, PasswordChar, SelText | Clear | Change, KeyPress, GotFocus, LostFocus |
CheckBox | Caption, Value (0/1) | Click | |
OptionButton | Caption, Value, Group | Click | |
ListBox | List, ListIndex, ListCount, Text | AddItem, RemoveItem, Clear | Click, DblClick |
ComboBox | List, ListIndex, ListCount, Text | AddItem, Clear | Click, Change |
Shape | Shape (Oval/Rectangle), FillColor, BorderColor | Click | |
ProgressBar | Value, Max | ||
Timer | Interval (ms), Enabled | Timer | |
MQTT | Broker, Port, ClientID, Username, Password, Subscriptions, AutoConnect, Connected | Connect, Disconnect, Publish, Subscribe, Unsubscribe | Connected, Disconnected, MessageArrived |
Form | Caption, Width, Height, BackColor | MsgBox, Unload | Load, Unload |
All visible controls also have Left, Top, Width, Height, Visible, Enabled,
FontName, FontSize, FontBold, Tag, SetFocus, Refresh; the plain-Tk ones have
BackColor and ForeColor. Ask the control_types tool for the authoritative list.
MCP tools
Tool | Classic RAD equivalent |
| Object browser |
|
|
|
|
| calling |
| (new) watch what the user does |
| the form designer |
| the toolbox |
| (new) the form's MQTT link, subscriptions and publishers |
| (new) webhook calls: counts, last error, which events call which URLs |
MQTT
Two styles, use either or both.
1. No code: subscribe, publish, mirror in the JSON
Add an mqtt block to the form, then give objects subscribe (a topic sets a
property) and publish (an event sends to a topic):
"mqtt": {"broker": "localhost", "port": 1883,
"prefix": "panelworks/cistern", "mirror": true},
"objects": {
"barLevel": {"type": "ProgressBar",
"subscribe": {"Value": {"topic": "homestead/cistern/level", "json": "level"}}},
"lblLevel": {"type": "Label",
"subscribe": {"Caption": {"topic": "homestead/cistern/level", "json": "level",
"format": "{:.0f} %"}}},
"shpPump": {"type": "Shape",
"subscribe": {"FillColor": {"topic": "homestead/pump/state",
"map": {"ON": "lime green", "OFF": "gray", "*": "orange"}}}},
"txtSetpoint": {"type": "TextBox",
"subscribe": {"Text": {"topic": "homestead/cistern/setpoint", "twoWay": true}}},
"cmdStart": {"type": "CommandButton",
"publish": {"Click": {"topic": "homestead/pump/cmd", "payload": "ON"}}}
}subscribe options, applied in this order to each incoming message (bind is
accepted as an older alias for subscribe):
Key | Does |
| Topic or wildcard filter ( |
| Pick a field from a JSON payload: |
| Translate values: |
| Multiply numeric values |
| Python format: |
| Publish back when the user changes it (TextBox.Text, CheckBox.Value, OptionButton.Value, ComboBox.Text/ListIndex, ListBox.ListIndex) |
| Publish two-way changes here instead of |
| Retain two-way publishes (default true) |
Connection options in the mqtt block:
Key | Default | Notes |
|
| Host name. |
| 1883, or 8883 with | |
|
| Encrypt the connection. Uses the operating system's trusted CAs (fine for Let's Encrypt) |
| Path to a CA certificate, for private or self-signed brokers | |
| Keep the password out of the file: | |
|
| Where mirror and status topics go |
|
| Publish |
If the broker refuses the login or can't be reached, the reason is printed once,
Form_MqttError(f, message) fires, and mqtt_status shows it as last_error.
The MQTT control has the same TLS, CAFile, Username and Password
properties, a LastError property, and an Error event.
publish takes one entry or a list per event. payload can template the
object's properties, e.g. "{Text}" or "{Value}". If no payload is given, it defaults to "{Value}"
or the event name. Optional retain and qos.
Incoming values that equal the current value are ignored, and a two-way change is never republished to the topic it arrived on, so there are no echo loops.
Mirror ("mirror": true) publishes every property of every object, retained,
to <prefix>/<object>/<property> whenever it changes (checked every
mirrorInterval ms, default 250). It publishes events (except Timer) to <prefix>/<object>/event.
Writing <prefix>/<object>/<property>/set sets that property, so
mosquitto_pub -t panelworks/cistern/lblLevel/Caption/set -m hi works. <prefix>/status
is online/offline (retained, with Last Will). Node-RED, n8n, Home Assistant
and ESP32s see the same object model Claude sees over MCP.
2. Code: the MQTT control (like the classic Winsock control)
"mqttMon": {"type": "MQTT", "Broker": "localhost",
"Subscriptions": ["homestead/pump/#"]}def mqttMon_MessageArrived(f, topic, payload, retained):
f.lstLog.AddItem(f"{topic} = {payload}")
def cmdFlush_Click(f):
f.mqttMon.Publish("homestead/valve/flush", "OPEN")It connects on Form_Load (AutoConnect), reconnects by itself, and re-subscribes
after a reconnect.
Try it
mosquitto # any broker on localhost:1883
python tests/fake_esp32.py # simulated cistern node
panelworks examples/cistern_mqtt.json
mosquitto_sub -t 'panelworks/cistern/#' -v # watch the form mirror itselfn8n (and any HTTP webhook)
Any event can POST to a webhook, and the reply drives the form, so an n8n workflow can act as an event procedure, with all of n8n's nodes and credentials behind it. It works from behind any firewall, because the panel always calls out.
"webhooks": {"baseUrl": "${N8N_WEBHOOK_BASE:-https://n8n.example.com/webhook/}",
"headers": {"X-Panel-Key": "${PANEL_KEY}"},
"poll": {"url": "panel-poll", "interval": 10}},
"objects": {
"cmdAsk": {"type": "CommandButton", "Caption": "Ask n8n",
"webhook": {"Click": {"url": "panelworks-demo", "send": ["txtName.Text"]}}}
}The panel POSTs:
{"form": "N8nDemo", "object": "cmdAsk", "event": "Click", "args": [],
"values": {"txtName.Text": "Steve"}, "time": 1795148800.0}and applies whatever JSON comes back (use a Respond to Webhook node):
{"set": {"lblReply.Caption": "Hello Steve", "shpLamp.FillColor": "dodger blue"},
"call": [["lstLog", "AddItem", "handled by n8n", 0]],
"msgbox": "optional pop-up"}sendlists theObject.Propertyvalues to include. The form itself isForm.pollcalls the URL everyintervalseconds as eventPollon objectForm, so n8n can push changes to the panel without being able to reach it.${VAR}and${VAR:-default}inbaseUrl,urlandheadersread environment variables, so keys and your server address stay out of files you commit.After a reply, the form fires
Object_WebhookResponse(f, data). On failure (unreachable, HTTP error, bad reply) it firesObject_WebhookError(f, message). Requests run on a background thread, so a slow n8n never freezes the window.The
webhook_statusMCP tool shows sent/ok/failed counts and the last error.
Try it: import examples/n8n/panelworks-demo.workflow.json into n8n
(Workflows → Import from File), publish it, then:
set N8N_WEBHOOK_BASE=https://your-n8n/webhook/ (PowerShell: $env:N8N_WEBHOOK_BASE="...")
panelworks examples/n8n_demo.jsonFor Claude Desktop, put the variable in the server's "env" block:
"env": {"N8N_WEBHOOK_BASE": "https://your-n8n/webhook/"}.
Example: HVAC console (real devices, MQTT over TLS)

examples/hvac_console.json watches two ESP32s, a thermostat display (cyd1) and
a relay board (relay1), through a TLS broker. Every value on screen is a
subscribe entry: room temperature, humidity, setpoint, mode, relay lamps, device
online lamps, the thermostat-to-relay BLE link, outdoor temperature and forecast
advice. The code module only keeps a change log.
It is read-only by design. The relays drive HVAC contactors and the thermostat
already commands them, so the console publishes nothing to home/.... Give it a
broker account that can only read:
# Mosquitto ACL
user panelworks
topic read home/#
topic readwrite panelworks/#Connection details come from environment variables, so nothing secret is in the file:
$env:PW_MQTT_HOST="mqtt.example.com" # your broker (TLS, port 8883 unless PW_MQTT_PORT is set)
$env:PW_MQTT_USER="panelworks"
$env:PW_MQTT_PASS="..."
panelworks examples/hvac_console.json --mcp noneMissing JSON fields (for example partial telemetry while a device boots) are skipped and the last value is kept.
One window per form
The first panelworks process to open a form takes an OS file lock (temp folder,
keyed by the form's full path) and owns the window. A second --mcp stdio launch
of the same form, which Claude Desktop typically does at startup, opens no window and relays its
MCP calls to the first over a localhost port, so every client drives the same
live form. A second launch in other modes prints "already open" and exits. The
OS releases the lock if the owner dies, even when it's killed from Task Manager.
When Claude Desktop quits (stdin closes), the form closes too, so no orphaned windows are left behind.
Thread model
Tkinter (like classic VB) only allows the GUI thread to touch controls. The MCP server and
paho's MQTT network thread both run in the background. Neither touches a widget.
MCP calls go through Form.call_on_gui(), which queues the call and waits for the
result on a Future; incoming MQTT messages go through Form.post(), which queues
without waiting. The GUI thread drains the queue every 20 ms (root.after). wait_for_event blocks only the MCP thread, so an agent
can wait for "user pressed Start" without freezing the window.
Not yet built
Visual drag-and-drop designer (today: edit JSON, or have Claude
add_object)Frame/container controls, menus, PictureBox/Canvas drawing, multiple forms
MQTT over TLS (paho supports it; just needs config keys)
License
MIT. See LICENSE. Free to use, modify and share, with no warranty.
About
PanelWorks is built by Steve Spence (KK4HFJ), homesteader, ham and long-time automation tinkerer. More projects and free downloads at kk4hfj.com.
If you build business tools, have a look at OfficeNex, business apps (document control, help desk and more) from the same workshop.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Manage tickets, run agents and workflows, query tables, and search workspace knowledge.
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to observe and control Windows desktop applications by reading UIA element trees and capturing screenshots, then acting through UIA patterns or synthesized mouse and keyboard input. It runs standalone on an interactive Windows session, without requiring the original host application.1-
- AlicenseCqualityBmaintenanceEnables MCP clients to inspect desktop windows through accessibility trees and screenshots, perform actions on resolved UI elements, and verify expected conditions after those actions.731Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI agents to inspect and control Java Swing and AWT desktop applications through the JVM's accessibility tree, including finding elements, clicking, typing, reading tables, and managing windows without modifying or injecting into the target process.16139 PyPI1MIT
- AlicenseNot gradedqualityCmaintenanceGives an agent eyes and hands on Windows desktops: screenshots with grids and Set-of-Marks, offline OCR with word boxes, click_text, mouse/keyboard/drag/window control, UI Automation, and batched act-and-verify actions. Supports a read-only mode that disables all input plus per-action audit logging.MIT