Server and report commands¶
The long-running servers and the installation reports: mcp (the assistant's connection), viz (the web view), ha-config (Home Assistant YAML) and audit.
bussard mcp¶
Run the MCP server, so an LLM assistant can read the project, watch the bus and, at higher tiers, write. By default it talks over stdio: an MCP client starts the server itself and nothing connects to it. With --listen it serves the same tools over streamable HTTP for a client that takes a server URL (see Over HTTP).
$ bussard mcp --dir knx
Started from a terminal, the server prints how to register it once it is ready: the Claude Code command, claude mcp add knx -- <binary> mcp --dir <project folder> <your flags>, and the same server as a mcpServers JSON entry for Claude Desktop and other clients. Both use the absolute path of the running binary and the resolved project folder, so the registration does not depend on the client's working directory. Relative --keyring and --capture-db paths are made absolute.
| Flag | Default | Meaning |
|---|---|---|
--passive |
off | Never transmit on the bus; omits knx_read_group, knx_describe_device, knx_backup_device, knx_reconstruct_device and knx_bus_reconnect. |
--allow-writes |
off | Register knx_write_group and knx_run_tests. Mutually exclusive with --passive. |
--allow-programming |
off | Register the programming tier: knx_plan_device, knx_apply_device, knx_apply_status, knx_last_apply, knx_restore_parameters, knx_restore_tables, knx_restart_device, knx_clear_security_log and knx_interface_secure. Mutually exclusive with --passive. |
--plan-ttl-minutes <MINUTES> |
10 |
How long a knx_plan_device digest stays valid for knx_apply_device. Needs --allow-programming. |
--allow-remote-gateway |
off | Permit --allow-writes or --allow-programming against a non-loopback (real) gateway. Without it (or BUSSARD_ALLOW_REAL_GATEWAY=1) such a server refuses to start. |
--no-model-edits |
off | Withhold the tools that edit the project (knx_set_group, knx_remove_group, knx_add_link, knx_remove_link, knx_set_device, knx_set_parameter, knx_set_interface, knx_undo, knx_discard_edits, knx_scaffold_groups, knx_reserve_groups) and the certificate enrolment (knx_enroll_certificates, knx_enroll_status). They write the project's TOML files behind a history snapshot, or the key store, and never touch the bus, so they are registered by default. The flag keeps the older word for the project. |
--allow-home-assistant |
off | Register the Home Assistant tier (knx_ha_status, knx_ha_plan, knx_ha_apply and the three automation tools) when bussard.toml has a [home_assistant] table. Never touches the bus, so it combines with every tier, --passive included. Without the table the flag logs a warning and registers nothing. |
--capture-db <PATH> |
A bussard capture database that extends knx_recent_telegrams history beyond the in-memory ring. |
|
--keyring <FILE> |
the key store | ETS keyring export (.knxkeys) for KNX Data Secure. Password from BUSSARD_KEYRING_PASSWORD. See below. |
--listen [<ADDR>] |
stdio | Serve streamable HTTP at http://<ADDR>/mcp instead of stdio. Without a value it binds 127.0.0.1:0, a free port, and prints the URL. A non-loopback address is refused without --allow-remote-clients. |
--allow-remote-clients |
off | Permit a non-loopback --listen address. Every request must then carry Authorization: Bearer <token>, with the token from BUSSARD_MCP_TOKEN or generated at start and printed once. Turns the Host header check off. Needs --listen. |
--allow-host <HOST> |
Also accept this Host header on a loopback --listen, for a reverse proxy or tunnel that forwards its public host name. Repeatable. Needs --listen. |
|
--viz-listen <ADDR> |
127.0.0.1:0 | Where knx_viz serves the browser page, read-only like a bare bussard viz. Without it the page takes a free loopback port on the first knx_viz. |
What --keyring covers:
knx_describe_deviceandknx_plan_devicewrap their session with the target's tool key, asbussard describe --keyringandbussard plan --keyringdo. A device the keyring does not list is read in the clear through the secure tunnel, unless the project marks itsecurity.activated(secured); then they refuse.knx_apply_devicewrites a device the keyring lists over KNX Data Secure and reprograms its security object, asbussard apply --keyringdoes.- Its group keys secure
knx_read_groupandknx_write_groupon a secured group address (the results carrysecured). A secured group address without a key is refused. - Secured telegrams on the live bus are decrypted (
knx_wait_for_telegram,knx_recent_telegrams,knx_infer_group), and so are those re-decoded from--capture-db. knx_validatechecks the keyring against the project.
Behaviour:
- The tiers, what each tool does and the gates in front of the programming and Home Assistant tiers are on MCP tools.
- Every device or Home Assistant write over MCP needs a plan the human approved with an explicit yes in the conversation, checked by a single-use, time-limited plan digest.
- No password is printed. When
BUSSARD_KEYRING_PASSWORD(or the--secure-password-envvariable) is exported, a line says the client must provide it and the JSON carries a<password>placeholder. When it comes from the.envin or next to the project folder, a line says the server reads that file itself. - A client that spawns the server with piped stderr gets none of the registration text, only the info-level log line
mcp: serving on stdio(visible with-v).
Claude Desktop. Settings > Developer > Edit Config opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). Paste the entry and restart Claude Desktop. The server shows under the tools icon in a chat, not in the connector list. The custom connector dialog takes only the HTTPS URL of a remote server: use --listen behind a TLS front (see below).
Over HTTP¶
$ bussard mcp --dir knx --listen 127.0.0.1:8765
bussard mcp serving streamable HTTP on http://127.0.0.1:8765/mcp (Ctrl-C to stop)
The tools, the tiers and the real-gateway write gate are the same as over stdio: --allow-writes, --allow-programming, --passive, --no-model-edits and --allow-remote-gateway mean the same thing. Every client session shares the server's one bus connection. Register it with Claude Code as claude mcp add --transport http knx http://127.0.0.1:8765/mcp; started from a terminal, the server prints that command. Port 0 (the default) picks a new port on every start, so pass a fixed one for a lasting registration.
- bussard does not terminate TLS and, on a loopback bind, does not authenticate clients. Claude Desktop's custom connectors need an
https://URL, so run a reverse proxy or a tunnel in front of the loopback port that terminates TLS and authenticates its users. That is the operator's job. A proxy that forwards its public host name needs--allow-host <name>; without it the server answers403, which blocks DNS rebinding from a browser. - A non-loopback
--listenaddress is refused unless--allow-remote-clientsis given. With it, every request needsAuthorization: Bearer <token>. Set the token inBUSSARD_MCP_TOKEN, or let the server generate one and print it once. The traffic is still plain HTTP: keep it on a network you trust, or behind TLS. BUSSARD_MCP_TOKEN, when set, is required on a loopback bind too.
macOS Local Network permission. macOS asks whether bussard may find and connect to devices on the local network. Without it the interface is unreachable and the bus status reports that the operating system refused access to the local network. Allow it in the prompt or under System Settings > Privacy & Security > Local Network. macOS ties the permission to the binary, so a rebuilt or updated bussard needs it again. A server still running from the old binary loses it as soon as the new one is allowed: restart Claude Desktop after allowing, and check that no old bussard mcp process is left.
bussard viz¶
Serve the network-visualization website: an HTTP server that renders the project as a bus-spine diagram and streams live traffic.
$ bussard viz
Open the listen address (http://127.0.0.1:8080 by default) in a browser. The page is self-contained: no CDN, no build step, and it works offline.
| Flag | Default | Meaning |
|---|---|---|
--listen <ADDR> |
127.0.0.1:8080 |
The address to bind the HTTP server to. A non-loopback bind is allowed but warns: the port is unauthenticated. |
--gateway <HOST> |
Gateway override. On connect failure the server degrades to offline mode. | |
--watch-prog |
off | Watch for devices in KNX programming mode and highlight them in the page. Active bus traffic: see below. |
--allow-writes |
off | Arm POST /api/group-write. Without it a bare bussard viz is a viewer, and the endpoint answers 403 writes_disabled. |
--allow-remote-gateway |
off | Permit --allow-writes or --watch-prog against a non-loopback (real) gateway. Without it such a server refuses to start. |
--keyring <FILE> |
Group keys (password in BUSSARD_KEYRING_PASSWORD). A write to a secured group address is sent as a secured group telegram (a secured address without a key answers 400), and secured telegrams in the live traffic are decrypted. |
|
--allow-host <HOST> |
Also answer requests whose Host header is this name (repeatable). Loopback names and bare IP literals are always accepted. |
The page shows the topology by floor and room, live traffic along the bus spine with a filterable log, the last value of each group address, a problems panel (com-objects without a link, group addresses without a sender or listener), per-DPT test-write widgets, an inspector with the selected device's com-objects and parameter values, and a ? help panel.
Behaviour:
- Structure is read-only: devices, groups and links are edited in the project files. The reload button next to the bus status re-reads the project and
bussard.lockwithout a restart and keeps the traffic view; use it after animportorapply. - Writes are off by default. With
--allow-writes, every send asks for a confirmation naming the group address and the resolved gateway, and aprotectedgroup address also needs the force checkbox. --watch-progbroadcastsA_IndividualAddress_Readevery few seconds. It is off by default and takes effect only when a bus is connected. Never point it at a real installation unattended.- The listen port is unauthenticated: anything that reaches it can read the whole project and, with
--allow-writes, write to the bus. Keep the default loopback bind unless you have a reason not to. - A request whose
Hostheader is not a bare IP literal,localhost(or a*.localhostname) or an--allow-hostname gets403 forbidden. This stops DNS rebinding. - A
POSTwhoseOriginis not an allowed host gets403 forbidden. A request with noOrigin(for examplecurl) is allowed. - If the gateway cannot be reached at startup, the server runs in offline mode: everything but live traffic works, and writes return
503. If the gateway drops mid-session, the server reconnects in the background; writes return503until the tunnel recovers. No restart is needed. - The server takes one tunnel for the whole session. Whether another tool (a
bussard write,flashorscan) can share the gateway at the same time depends on the gateway. To drive test traffic the page always sees, use the page's own writes. - The endpoints are on the viz API.
bussard ha-config¶
Generate the Home Assistant KNX integration YAML from the project.
$ bussard ha-config --out knx.yaml
| Flag | Default | Meaning |
|---|---|---|
--out <FILE> |
stdout | Output file. |
Behaviour:
- Reads the project and
ha.tomlonly; nothing reaches the bus or Home Assistant. - The derivation rules and the
ha.tomloverrides are on Home Assistant. - The MCP server's Home Assistant tier writes the same YAML to the file Home Assistant reads, after a plan the human approved (see MCP tools).
bussard audit¶
Report what the installation holds and what bussard can do with it. The static part reads only the project; --live adds a read-only look at the gateway and the bus.
$ bussard audit
$ bussard audit --live --window 60
| Flag | Default | Meaning |
|---|---|---|
--json |
off | Emit one JSON object instead of the sectioned text report: the same object the knx_audit MCP tool returns. |
--live |
off | Add the live part: gateway description, traffic sample, scan of the project's devices. |
--window <SECS> |
30 |
Traffic-sample window for --live. |
--keyring <FILE> |
the key store | An ETS .knxkeys keyring. Each Secure device is reported with or without a tool-key entry, and with --live probed over KNX Data Secure with its tool key. Password from BUSSARD_KEYRING_PASSWORD. No key material is printed. |
--skip-address-check |
off | With --live, skip the check that no bus device answers at bussard's own source address before the scan (see Device support). |
Static sections (JSON keys in brackets):
- Model (
model): device count per line, devices without a name or a location, group addresses without a DPT or a name (including ones only device files link), links to com-objects the device file does not declare, links for addresses with no device file, protected group addresses, project name and import source. - Findings (
model.findings): one-sided links only, a group address with senders but no listener or listeners but no sender. Unlinked com-objects (I009: a T or W object in no link) and unused group addresses (I010) are counted inmodel.infoas neutral information. The analysis is built from thevalidatediagnostics (I048 and I049 are the findings), so the audit, the viz problems panel andbussard validatereport the same cases. - Devices per mask (
masks): devices grouped by theproduct.masktheir file records, with what bussard can do (plan_apply,flash,reconstruct,describe). The column comes from the same table theplan,apply,flashandreconstructrefusals use. - Supported devices (
support): how many devices a write passes without the override, by the device-support list (devices,supported, and per categoryprovenandlikely, the latter not confirmed on a real device), and each device a write refuses (unsupported:address,support) with the lineplananddescribeprint (not listed, or a known problem with its issue). - KNX Secure (
secure): devices that support Secure and secured devices, and with--keyringwhether the keyring holds each one's tool key.
Live sections (live, with --live):
- Gateway (
live.gateway): name, address andN tunnels, M in usefrom the interface's description. - Traffic sample (
live.traffic): group telegrams seen during--window, per group address with its repetition rate, group addresses sent on the bus that have no listener in the project, and source addresses that are not in the project. - Scan delta (
live.scan): every device in the project probed, one at a time and at most one probe per 250 ms, per line: which answered (with a mask mismatch against the project flagged) and which did not. Only the project's addresses are probed; unexpected devices show up as unknown traffic sources, or runbussard scan. A Data Secure device's row carriessecureand the real mask when the secured probe read it; a hiddenFFFFmask is never flagged as a mismatch. - KNX Secure (live) (
live.secure): every Data Secure device (one that answers the plain probe with maskFFFF, has asecurity:block in the project, or is in the keyring) withactivated,reachable_secured(nullwhen no secured probe ran),plain_reads_refused,in_keyring(nullwithout--keyring), the realmask, and onestatus:reachable_secured,key_refused,not_in_keyring,plain_reads_refused(no keyring given),plain, ornot_answering.
Behaviour:
- Read-only. The live part sends only management reads (device descriptor, authorize, device-object properties) to device addresses, and never a group telegram.
- Exits 0 on a completed audit. A full interface (no free tunnel) stops the audit with exit code
4. - Each scanned device carries its identity verdict against
bussard.lock(seeplan).
Details
Repetition counts frames marked repeated in the cEMI control field, and identical telegrams from the same source within 500 ms. The secured probe runs like describe --keyring: S-A_Sync, then the descriptor and device-object property reads inside A_SecureData.
Related¶
- MCP tools: every tool, the tiers and the bus connection.
- The viz API: the JSON and SSE endpoints behind the page.
- Connect an assistant: register
bussard mcpand hold the first conversation. - Find what you have:
auditin a task.