qb-mcp-server

A local MCP server that exposes the Qbee device-management REST API as tools over the streamable HTTP transport. It lets MCP clients (Claude Code, Claude Desktop, …) answer questions about your Qbee-managed device fleet and perform tiered write operations: staged configuration commits, file management, device metadata, enrollment approvals, IAM, and bootstrap keys.

⚠️ Caveat Emptor (Buyer Beware)

You are about to hand an LLM the keys to a device fleet. That is powerful — and occasionally hilarious — right up until a slightly misread request renames every device in a group or commits a config you meant to keep as a draft.

The guardrails are real but not magic: consequential tools are confirm-gated (the target must be restated exactly), every mutation is audited to stderr, irreversible deletions aren't exposed at all, and QBEE_MCP_ALLOW_WRITES=false takes every write tool off the table. What no guardrail can do is decide whether a request was a good idea — that part stays with you. Sensible habits:

• Learn on a scratch device (a hello-world, if you will) before pointing this at production fleets.

• Review qb_changes_list before every qb_config_commit — commit applies to real hardware.

• Give the account a Qbee role with the narrowest permissions that still work.

• Remember: the undo button for a commit is usually another commit.

Related MCP server: mcp-kubernetes

Requirements

• Node.js ≥ 20

• A Qbee account without 2FA enabled (see Troubleshooting)

Configuration

Credentials and the API base URL live in ~/.config/qbee-fleet/config.json (override the path with QBEE_CONFIG_PATH):

{
  "server": "https://www.app.qbee.io",
  "username": "you@example.com",
  "password": "your-password"
}

The file is read once at startup. Its values are secrets: they are never logged, never returned through MCP, and error messages name only the file path.

Run

npm install
npm run build
npm start          # listens on http://127.0.0.1:3333/mcp

Development: npm run dev (tsx watch) · Tests: npm test

Environment variables

Add to an MCP client

Point any streamable-HTTP MCP client at http://127.0.0.1:3333/mcp, e.g.:

claude mcp add --transport http qb http://127.0.0.1:3333/mcp

How auth works

The server exchanges username/password for a short-lived JWT (POST /api/v2/login) on the first tool call, caches it in memory only, and re-logs in automatically before it expires or after any 401. Nothing is persisted to disk.

GET /healthz (outside MCP) reports liveness and auth state: {"ok": true, "auth": "pending" | "authenticated" | "failed"}.

Tools (52)

Reads (29)

Writes — Tier 1, no confirmation (6)

Reversible, cosmetic operations: qb_reports_mark_read, qb_file_create_dir, qb_device_attributes_update (name/description/location/tags), qb_notifications_update, qb_profile_update, qb_cve_update (enable/disable).

Writes — Tier 2, confirmation-gated (17)

Fleet- or account-affecting operations. Each requires a confirm argument that must exactly echo the operation's primary target identifier — a deliberate restatement, not a yes/no. Mismatched or missing confirm fails before any HTTP request.

Configuration workflow: changes are staged (qb_config_change_stage), reviewed (qb_changes_list / qb_change_get), then applied fleet-wide by qb_config_commit. The commit tool deliberately sends only a message — it commits what is already staged and can never smuggle inline changes.

Deliberately not exposed: device removal, company settings/deletion, user/role deletion, host un-approval, whole-tree group replacement, bulk staged-change discard, auth-provider toggles, and the 2FA flow. Use the Qbee web UI for those.

Safety rails

• Confirm-echo gate on every Tier-2 tool (see above); failures happen before any network request.

• Audit log: every mutating call emits one stderr JSON line (ts, tool, target, tier, outcome) — never arguments, credentials, or tokens.

• Kill-switch: QBEE_MCP_ALLOW_WRITES=false removes all write tools from the catalog; reads stay.

• Large results are truncated at 256 KB with a notice; narrow queries with pagination and search parameters.

Troubleshooting

• qbee login failed: Invalid credentials. — the config file's username/password were rejected (HTTP 400 from Qbee). Check for typos or an outdated password.

• qbee login requires two-factor authentication … — the account has 2FA enabled, which this server does not support. Use a non-2FA account or a service account.

• qbee unreachable: … — the server URL could not be reached (network, DNS, or wrong URL).

• qbee API 403: … — authenticated, but your Qbee role lacks the permission the endpoint needs (e.g. device:read, files:manage).

• refused: this operation is confirmation-gated … — the confirm argument didn't exactly match the named target argument; restate the target.

• Port already in use — set QBEE_MCP_PORT.

Disclaimer

This project is an independent open-source tool and is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Qbee AS, or any of its subsidiaries or affiliates.

The official Qbee website can be found at https://qbee.io.

The name "Qbee" as well as related names, marks, emblems, and images are registered trademarks of their respective owners. Any use of trademarked terms in this repository is strictly for nominative, referential, or identification purposes only and does not imply any endorsement or sponsorship.

License

Copyright 2026 BigPod Limited. Licensed under the Apache License, Version 2.0.