tronbyt-mcp

tronbyt-mcp

让 AI 助手为你的 LED 显示屏显示内容。

如果你有一台 Tidbyt 或 Tidbyt 风格的 LED 矩阵显示屏，并由可自托管的 tronbyt/server 管理，此工具可将其连接到 Claude（或任何支持 MCP 的其他 AI 工具。MCP 是一项开放标准，旨在让助手能够访问工具）。安装后，你就可以直接向助手提出有关显示屏的请求：

“在显示屏上用琥珀色显示 BREAD'S DONE。” “把显示屏调暗到 20%，并开启夜间模式，时间设为晚上 10 点到早上 7 点。” “现在显示屏上有哪些应用？禁用股票行情。” “显示一会儿时钟应用。”

助手会处理剩下的工作：将文本渲染为显示屏的像素格式、与服务器通信、管理应用轮播。所有操作都在你自己的机器上，通过你自己的服务器运行；不会经过任何云服务。

工作原理

tronbyt-mcp 是一个小型 MCP 服务，用于封装 tronbyt/server 文档中说明的 REST API。你的 MCP 客户端（Claude Code、Claude Desktop 等）会在本地启动它，并通过 stdio 与其通信；它则使用设备 API 密钥，通过 HTTP 与 Tronbyt 服务器通信。

要求

• 由可自托管的 tronbyt/server（v2.x）管理的显示屏。服务器管理的任何设备都可使用，不要求设备最初就是 Tidbyt：Tidbyt Gen1/Gen2、 Tronbyt S3 和 S3 Wide 套件、MatrixPortal S3（包括 Waveshare 变体）、 Waveshare S3、Pixoticker、Raspberry Pi 显示屏，以及标记为 “other” 的自制面板。 支持标准的 64×32 和宽屏 128×64（2x）面板。
• Node.js ≥ 20.9
• MCP 客户端：Claude Code、Claude Desktop，或任何其他支持 MCP stdio 服务的客户端。

安装

1. 获取设备 API 密钥

在 Tronbyt 网页界面中，打开设备设置并复制（或生成）其 API 密钥。密钥仅适用于单台设备——一个密钥对应一台显示屏。

2. 将服务添加到 MCP 客户端

Claude Code（一条命令）：

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：编辑配置文件—— macOS：~/Library/Application Support/Claude/claude_desktop_config.json， Windows：%APPDATA%\Claude\claude_desktop_config.json——然后添加：

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

然后重启 Claude Desktop。

任何其他 MCP 客户端：配置一个 stdio 服务，命令为 npx，参数为 ["-y", "tronbyt-mcp"]，并设置上面的两个环境变量。

从源码安装（而不是使用 npx）：

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

然后在 MCP 客户端配置中，将 node /path/to/tronbyt-mcp/dist/index.js 用作服务命令（环境变量相同）。

有多台显示屏？ API 密钥按设备区分，因此每台显示屏都添加一项 （tronbyt-kitchen、tronbyt-office……），并为每项设置各自的密钥。

3. 检查是否正常工作

向助手提出类似 “列出我的 Tronbyt 设备。” 的问题。你应该会看到显示屏及其亮度、夜间模式和应用列表。（在 Claude Code 中，/mcp 也会显示该服务及其工具。）

配置

环境变量	必填	默认值	说明
TRONBYT_BASE_URL	是	—	你的 tronbyt/server，例如 http://tronbyt.local:8000
TRONBYT_API_KEY	是	—	从 Tronbyt 网页界面获取的设备专属 API 密钥
TRONBYT_TIMEOUT_MS	否	10000	每个请求的超时时间

使用方法

你无需直接调用这些工具——助手会根据你的请求选择合适的工具—— 但它可用的工具如下：

工具	功能
list_devices	此密钥可见的设备：亮度、夜间模式、置顶应用、上次在线时间
update_device	设置亮度、轮播间隔、夜间／调暗模式、置顶应用
reboot_device	重启显示屏
list_installations	设备上已安装的应用及其状态和配置
update_installation	启用／停用、置顶／取消置顶，或调整安装项的显示时间
delete_installation	移除安装项及其渲染图像
push_app	渲染服务端应用（可选配置）并显示
push_image	将 base64 WebP（64×32，宽屏显示器为 128×64）直接推送到显示屏
push_text	在本地将文本渲染为适合显示屏尺寸的 WebP 并推送

推送工具接受 background 参数：false（默认值）会中断显示并立即显示推送内容；true 会将其保存到轮播中，不中断当前显示。当密钥只关联一台设备（通常如此）时，无需指定 device_id。

push_text

文本使用 Tom Thumb 3×5 像素字体渲染，并自动换行、居中。仅支持可打印的 ASCII 字符；\n 可强制换行。颜色使用十六进制值（#ffcc00），默认为黑底白字。

画布尺寸会根据设备类型自动检测（size: "auto"）：标准显示屏为 64×32，宽屏／2x 显示屏（tronbyt_s3_wide、raspberrypi_wide）为 128×64。宽屏显示器默认会将字体放大一倍——字符数仍为 16 个、行数仍为 5 行，像素尺寸加倍。传入 text_size: "small" 可使用原始尺寸的字形（32 个字符 × 10 行），也可通过 size: "64x32"／"128x64" 完全覆盖自动检测结果。

移除

• Claude Code： claude mcp remove tronbyt
• Claude Desktop／其他客户端： 从配置文件中删除 "tronbyt" 条目，然后重启客户端。
• 如果你是从源代码安装的： 删除克隆的目录。如果使用了 npx，缓存副本可能会留在 ~/.npm/_npx 下；它体积很小且无害，也可以使用 npm cache clean --force 清除。
• 在服务器上： 你推送的内容都会作为安装项显示在设备上——请让助手删除，或在 Tronbyt 网页界面中移除。如果不再使用 API 密钥，请在网页界面中撤销。其他内容不会存储在任何地方。

开发

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

针对真实服务器进行冒烟测试（不会造成破坏——以后台模式推送到轮播中，然后删除安装项）。构建完成后，从仓库根目录运行：

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

范围之外（v1）

• update_firmware_settings——特意排除；错误的值可能导致显示屏无法访问
• 动画（多帧 WebP）、通过 URL 获取图像
• HTTP 传输（仅限 stdio）

许可证

MIT。捆绑的像素字体是 Brian J. Swetland 和 Robey Pointer 编写的 Tom Thumb／“Fixed4x6”（MIT），随项目提供于 scripts/tom-thumb.bdf。本项目与 Tidbyt（公司）或 Tronbyt 项目无关联。