Skip to content

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_device and knx_plan_device wrap their session with the target's tool key, as bussard describe --keyring and bussard plan --keyring do. A device the keyring does not list is read in the clear through the secure tunnel, unless the project marks it security.activated (secured); then they refuse.
  • knx_apply_device writes a device the keyring lists over KNX Data Secure and reprograms its security object, as bussard apply --keyring does.
  • Its group keys secure knx_read_group and knx_write_group on a secured group address (the results carry secured). 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_validate checks 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-env variable) is exported, a line says the client must provide it and the JSON carries a <password> placeholder. When it comes from the .env in 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 answers 403, which blocks DNS rebinding from a browser.
  • A non-loopback --listen address is refused unless --allow-remote-clients is given. With it, every request needs Authorization: Bearer <token>. Set the token in BUSSARD_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.lock without a restart and keeps the traffic view; use it after an import or apply.
  • Writes are off by default. With --allow-writes, every send asks for a confirmation naming the group address and the resolved gateway, and a protected group address also needs the force checkbox.
  • --watch-prog broadcasts A_IndividualAddress_Read every 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 Host header is not a bare IP literal, localhost (or a *.localhost name) or an --allow-host name gets 403 forbidden. This stops DNS rebinding.
  • A POST whose Origin is not an allowed host gets 403 forbidden. A request with no Origin (for example curl) 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 return 503 until the tunnel recovers. No restart is needed.
  • The server takes one tunnel for the whole session. Whether another tool (a bussard write, flash or scan) 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.toml only; nothing reaches the bus or Home Assistant.
  • The derivation rules and the ha.toml overrides 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 in model.info as neutral information. The analysis is built from the validate diagnostics (I048 and I049 are the findings), so the audit, the viz problems panel and bussard validate report the same cases.
  • Devices per mask (masks): devices grouped by the product.mask their file records, with what bussard can do (plan_apply, flash, reconstruct, describe). The column comes from the same table the plan, apply, flash and reconstruct refusals use.
  • Supported devices (support): how many devices a write passes without the override, by the device-support list (devices, supported, and per category proven and likely, the latter not confirmed on a real device), and each device a write refuses (unsupported: address, support) with the line plan and describe print (not listed, or a known problem with its issue).
  • KNX Secure (secure): devices that support Secure and secured devices, and with --keyring whether the keyring holds each one's tool key.

Live sections (live, with --live):

  • Gateway (live.gateway): name, address and N tunnels, M in use from 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 run bussard scan. A Data Secure device's row carries secure and the real mask when the secured probe read it; a hidden FFFF mask is never flagged as a mismatch.
  • KNX Secure (live) (live.secure): every Data Secure device (one that answers the plain probe with mask FFFF, has a security: block in the project, or is in the keyring) with activated, reachable_secured (null when no secured probe ran), plain_reads_refused, in_keyring (null without --keyring), the real mask, and one status: reachable_secured, key_refused, not_in_keyring, plain_reads_refused (no keyring given), plain, or not_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 (see plan).
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.