Kbox ETS MCP

Kbox ETS MCP is an ETS App that lets an AI agent read and work on the KNX project you currently have open in ETS6. It runs inside ETS, so the agent sees the live project — the same topology, devices, group addresses and parameters you see on screen.

This guide takes you from installing the app to asking Claude its first question.

Before you start

  • ETS 6 installed, with a project open. The server has nothing to talk about until a project is open.
  • A Kbox account, for the remote connection. You will sign in with it once.
  • An MCP-capable agent — Claude on the web, Claude Desktop, Codex or Gemini CLI. Any of them works; what differs is only where you paste the address.

1. Install the ETS App

Install the .etsapp file the way you install any ETS App. There is no need to restart ETS — the app is available as soon as it is installed.

2. Open the panel

The app does not open by itself and it does not add a tab of its own. Open it from the toolbar: Panels → All Panels → Kbox → Kbox ETS MCP.

Opening the app from the Panels menu

Everything in this guide happens in that panel. Click the star beside Kbox ETS MCP to pin it, and it is one click away next time.

The Kbox ETS MCP panel in ETS

Read the warning before you connect

The panel opens with a deliberate warning, and it is worth a moment:

This server can give a connected AI agent the full topology of this building, its complete device inventory, and the firmware state of every device on the bus. That data typically leaves your computer and is processed by a cloud-hosted language model. Read-only access already exposes all of this; the write and online tiers additionally let the agent change the project or the running installation.

In other words: even the safest tier sends your project's contents to a language model. Decide with that in mind.

3. Choose what Claude may do

Three tiers, each including everything the one above it allows:

  • Read only — read the project, catalogue and master data. Nothing is changed.
  • Can edit the project — modify the open project. Every change is wrapped in an ETS undo marker, so it can be reverted from ETS.
  • Can talk to devices — communicate with real hardware over the bus: reads, writes, downloads and firmware updates. Irreversible, and confirmed individually every time.

Two safeguards are built in and cannot be switched off:

  • An agent cannot raise its own tier. Only the person sitting in front of ETS can arm write or online access.
  • Elevated permissions reset to read-only every time ETS starts. Arming write or online access is a decision for the current session only.

Tool groups

Under Which tools are on? you can switch off whole groups — Topology, Group addresses, Communication objects, Parameters, Buildings, Catalog, Undo history, Bus, Device management, Network management, Commissioning, Jobs, Export, Navigation. A group you turn off is not offered to the agent at all.

4. Connect

There are two routes. Pick one.

Option A — From somewhere else (the default)

This is the choice the panel starts on. Use it for Claude on the web, or whenever the agent is not running on the ETS machine. It is two steps: first you allow this computer, then you introduce the project to Claude. Nothing connects until you press these buttons yourself.

Allowing this computer and finding the server address

Step 1 — Allow this computer

The panel shows an address that already carries your code, for example https://id.kboxsolutions.com/device?user_code=XXXX-XXXX.

  1. Press Copy.
  2. Open that address in a browser — on this computer or on your phone.
  3. Check that the page shows the same code the panel shows.
  4. Sign in with your Kbox account and approve.

The panel waits while you do this, and moves on by itself once you approve. If you change your mind, press Cancel. Revoke this computer's access undoes the approval later.

Step 2 — Introduce this project to Claude

Copy the Server address from the panel — https://mcp.etsmcp.kboxsolutions.com/mcp — then set it up in Claude.

Open Claude, go to Customize → Connectors:

Claude's connector list

Press + Add, give it a name and paste the server address:

Adding a custom connector

Claude detects how to sign in. The defaults shown as Detected are the right ones — Sign in now and Use Claude's published identity. Leave Request headers empty; this server does not need one.

Authentication options

Press Add. The connector appears but is not connected yet — press Connect:

The connector, not yet connected

You are sent to the Kbox sign-in page to authorize Claude:

Authorizing Claude for your Kbox account

The account box is blanked out in this guide; yours shows your own user ID and e-mail address. The page lists exactly what you are granting:

  • Read your ETS project — topology, devices, group addresses, parameters and the product catalogue.
  • Change your ETS project — create and edit group addresses, parameters, devices and topology. Each change is one undoable entry in ETS.

Press Authorize and you are returned to Claude, connected.

This grant is a ceiling, not a switch. Authorizing project changes here does not turn them on. The agent can only do what both this grant and the tier armed in the ETS panel allow — and the ETS side goes back to read-only every time ETS restarts.

Option B — On this computer

Only for an agent running on the ETS machine itself. There is no pairing and no Kbox account: the agent talks to the server over the machine's own network loopback.

Connecting an agent on this computer

  1. Choose On this computer.
  2. Copy the Endpoint with the button beside it.
  3. Copy the Access token the same way. Show reveals it if you want to read it, but you do not have to reveal it in order to copy it.
  4. In your agent, add this as an MCP server over HTTP with that endpoint, and send the token as a bearer token. In Claude Desktop that is a custom connector; Codex and Gemini CLI take both on the command line.

Two things worth knowing:

  • Use the address exactly as the panel shows it — it starts http://127.0.0.1. Writing localhost instead will not work: the server checks the address your agent sends.
  • You only do this once. The endpoint and the token stay the same when ETS restarts. They change if you press Regenerate, which is how you disconnect every agent at once.

Upgrading from an older version? Earlier releases had a Connect Claude Desktop button that wrote Claude Desktop's configuration for you. That button is gone, and the entry it wrote no longer points at anything — remove it and set up a custom connector as above.

5. Set tool permissions in Claude

Claude groups the server's tools into read-only and write/delete, and lets you decide when each may run: Always allow, Needs approval, or Blocked.

Read-only tool permissions

Write and delete tool permissions

A reasonable starting point: leave the read-only tools on Always allow, and set the write/delete group to Needs approval until you trust what the agent does with your project. You can override individual tools within a group.

This is a second, independent brake. It does not replace the ETS tier — it narrows what a tier already permits.

6. Ask it something

Open a conversation and ask about the project. For example:

  • "How many devices are in this project, and which lines are they on?"
  • "List every group address under 1/2 and tell me which devices are linked to each."
  • "Which communication objects on the thermostat in the living room are unlinked?"
  • "Create group addresses 0/3/1 to 0/3/8 named Kitchen Light 1 … 8."

Changes land in ETS as you watch. Each one is a single entry in ETS's own undo list, so Ctrl+Z in ETS reverts it.

Anything that touches real hardware — a bus read or write, a download, a firmware update — opens a confirmation dialog in ETS and waits for a person to answer. The agent cannot confirm it for you.

7. Other agents (Codex, Gemini CLI)

There is nothing extra to set up. Any agent on the ETS machine uses the same Endpoint and Access token as Option B above; Codex and Gemini CLI take both on the command line.

Advanced repeats them, next to the things you need only occasionally:

The Advanced section

  • Endpoint — the local address the server is listening on, normally http://127.0.0.1:48610/mcp. If something else on the machine already holds that port, the server takes another one and shows it here.
  • Access token — the same value as in Option B. Regenerate issues a new one immediately, and every agent you configured stops working until you paste the new one in. That is the point of it: it is how you cut all of them off at once.
  • Export directory — where exported files are written.

Turn access off stops the server without closing ETS.

Things worth knowing

  • A project must be open in ETS. With no project open, the tools refuse and tell you so.
  • The permission tier resets to read-only on every ETS restart — by design, not a bug.
  • Project changes are undoable from ETS. Bus operations are not; that is why each one is confirmed separately.
  • The agent never sees your ETS password or your Kbox password. Signing in happens in your browser, and the server only ever receives a token.

Troubleshooting

  • The agent says no project is open — open a project in ETS, then retry.
  • The agent says it lacks permission — arm a higher tier in the ETS panel. Remember it resets when ETS restarts. Also check the tool is not Blocked in Claude's connector settings.
  • An agent on this computer stopped connecting — restarting ETS does not change the endpoint or the token, so check whether someone pressed Regenerate, and whether the panel still shows the port your agent is configured with.
  • The pairing code expired — press Cancel, then start step 1 again for a fresh code.
  • A tool group is missing — it is switched off under Which tools are on? in the panel.