tronbyt-mcp

tronbyt-mcp

Let your AI assistant put things on your LED sign.

If you have a Tidbyt or Tidbyt-style LED matrix display managed by a self-hosted tronbyt/server, this connects it to Claude (or any other AI tool that speaks MCP, the open standard for giving assistants access to tools). Once installed, your display becomes something you can just talk to your assistant about:

"Put BREAD'S DONE on the sign in amber." "Dim the display to 20% and turn on night mode from 10pm to 7am." "What apps are on the sign right now? Disable the stock ticker." "Show the clock app for a bit."

The assistant handles the rest — rendering text into the display's pixel format, talking to your server, managing the app rotation. Everything runs on your own machine against your own server; nothing goes through any cloud service.

How it works

tronbyt-mcp is a small MCP server that wraps tronbyt/server's documented REST API. Your MCP client (Claude Code, Claude Desktop, and friends) launches it locally and talks to it over stdio; it talks to your Tronbyt server over HTTP with a device API key.

Requirements

• A display managed by a self-hosted tronbyt/server (v2.x). Any device the server manages works — it doesn't need to have started life as a Tidbyt: Tidbyt Gen1/Gen2, Tronbyt S3 and S3 Wide kits, MatrixPortal S3 (including the Waveshare variant), Waveshare S3, Pixoticker, Raspberry Pi displays, and homebrew panels typed "other". Both standard 64×32 and wide 128×64 (2x) panels are supported.
• Node.js ≥ 20.9
• An MCP client: Claude Code, Claude Desktop, or anything else that supports MCP stdio servers.

Installation

1. Get a device API key

In the Tronbyt web UI, open your device's settings and copy (or generate) its API key. Keys are scoped to a single device — one key, one display.

2. Add the server to your MCP client

Claude Code (one command):

claude mcp add tronbyt \
  -e TRONBYT_BASE_URL=http://tronbyt.local:8000 \
  -e TRONBYT_API_KEY=<your-device-key> \
  -- npx -y tronbyt-mcp

Claude Desktop: edit the config file — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json — and add:

{
  "mcpServers": {
    "tronbyt": {
      "command": "npx",
      "args": ["-y", "tronbyt-mcp"],
      "env": {
        "TRONBYT_BASE_URL": "http://tronbyt.local:8000",
        "TRONBYT_API_KEY": "<your-device-key>"
      }
    }
  }
}

Then restart Claude Desktop.

Any other MCP client: configure a stdio server with command npx, args ["-y", "tronbyt-mcp"], and the two environment variables above.

From source (instead of npx):

git clone https://github.com/jonfishr/tronbyt-mcp.git
cd tronbyt-mcp
npm install && npm run build

Then use node /path/to/tronbyt-mcp/dist/index.js as the server command in your MCP client config (same environment variables).

Multiple displays? API keys are per-device, so add one entry per display (tronbyt-kitchen, tronbyt-office, …), each with its own key.

3. Check it works

Ask your assistant something like "List my Tronbyt devices." You should get back your display with its brightness, night mode, and app list. (In Claude Code, /mcp also shows the server and its tools.)

Configuration

Env var	Required	Default	Notes
TRONBYT_BASE_URL	yes	—	Your tronbyt/server, e.g. http://tronbyt.local:8000
TRONBYT_API_KEY	yes	—	Per-device API key from the Tronbyt web UI
TRONBYT_TIMEOUT_MS	no	10000	Per-request timeout

Usage

You don't call these directly — your assistant picks the right tool from your request — but this is what it has to work with:

Tool	What it does
list_devices	Devices visible to the key: brightness, night mode, pinned app, last seen
update_device	Set brightness, rotation interval, night/dim mode, pinned app
reboot_device	Reboot the display
list_installations	Apps installed on the device, with state and config
update_installation	Enable/disable, pin/unpin, or retime an installation
delete_installation	Remove an installation and its rendered images
push_app	Render a server-side app (with optional config) and show it
push_image	Push a base64 WebP (64×32, or 128×64 for wide displays) straight to the display
push_text	Render text to a display-sized WebP locally and push it

Push tools take background: false (default) interrupts the display and shows the push immediately; true saves it into the rotation without interrupting. When a key sees exactly one device (the normal case), device_id never needs to be specified.

push_text

Text is rendered with the Tom Thumb 3×5 pixel font, word-wrapped and centered. Printable ASCII only; \n forces a line break. Colors are hex (#ffcc00), default white on black.

Canvas size is detected from the device type (size: "auto"): standard displays get 64×32, wide/2x displays (tronbyt_s3_wide, raspberrypi_wide) get 128×64. On wide displays the font is doubled by default — same 16 chars × 5 lines, twice the pixels. Pass text_size: "small" for native-size glyphs (32 chars × 10 lines), or override the detection entirely with size: "64x32" / "128x64".

Removal

• Claude Code: claude mcp remove tronbyt
• Claude Desktop / other clients: delete the "tronbyt" entry from the config file and restart the client.
• If you installed from source: delete the cloned directory. If you used npx, a cached copy may linger under ~/.npm/_npx; it's small and harmless, or clear it with npm cache clean --force.
• On the server: anything you pushed shows up as an installation on the device — ask your assistant to delete it, or remove it in the Tronbyt web UI. Revoke the API key in the web UI if you're done with it. Nothing else is stored anywhere.

Development

npm install
npm test            # vitest: unit + in-process MCP + stdio e2e (builds first)
npm run build       # tsc -> dist/
npm run gen:font    # regenerate src/font.ts from scripts/tom-thumb.bdf

Smoke test against a real server (non-destructive — pushes to the rotation in background mode, then deletes the installation). Run from the repo root after a build:

TRONBYT_BASE_URL=http://tronbyt.local:8000 TRONBYT_API_KEY=<key> scripts/smoke.sh

Out of scope (v1)

• update_firmware_settings — deliberately excluded; a bad value can leave a display unreachable
• Animation (multi-frame WebP), image-by-URL
• HTTP transport (stdio only)

License

MIT. The bundled pixel font is Tom Thumb / "Fixed4x6" by Brian J. Swetland and Robey Pointer (MIT), vendored as scripts/tom-thumb.bdf. This project is not affiliated with Tidbyt (the company) or the Tronbyt project.