Content
# tronbyt-mcp
Let your AI assistant put things on your LED sign.
If you have a [Tidbyt](https://tidbyt.com) or Tidbyt-style LED matrix display managed by
a self-hosted [tronbyt/server](https://github.com/tronbyt/server), this connects it to
Claude (or any other AI tool that speaks [MCP](https://modelcontextprotocol.io), 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](https://github.com/tronbyt/server/blob/main/API.md). 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):
```sh
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:
```json
{
"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):
```sh
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](https://robey.lag.net/2010/01/23/tiny-monospace-font.html)
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
```sh
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:
```sh
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.
