TRMNL API MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TRMNL API MCP Show me my TRMNL playlist items and their visibility"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TRMNL API MCP
Local MCP access to read TRMNL devices and manage playlist items, visibility, ordering and weekly display windows. Built with the official MCP TypeScript SDK, using Node.js and stdio. This is an unofficial TRMNL integration. The current tool set covers playlists; the repository name leaves room for additional API support.
Repository: renzel/trmnl-api-mcp.
Tools
Tool | Inputs | Output |
| optional | Device names and numeric IDs, default refresh interval in seconds, sleep settings and last check-in |
| optional | Plugin names, visibility, ordering values, group/mashup IDs, configuration status and render timestamps |
|
| Weekly windows; day 0 is Sunday and day 6 is Saturday |
|
| Updated playlist entry |
|
| New entry for an existing plugin instance |
|
| Removal result |
|
| Ordering replacement result |
|
| Complete replacement schedule |
Lists default to 50 items and allow up to 100 per call. Follow next_offset until null. Pagination is local over the API's complete list response; each call makes one GET request. Responses remain in API order.
Related MCP server: Technitium DNS MCP
Connect
Prerequisites: Node.js 22+ and Python 3 for the hidden credential prompt.
In TRMNL Account, copy your User API Key. The per-plugin key beginning
ps_mcp_is not suitable.Run
python3 scripts/configure.pyfrom this directory in a terminal. The hidden prompt stores the token in~/.config/trmnl-playlist/account-api-keywith permissions 600, outside the project. Don't put it in chat, source files or command arguments.Run
npm ci --ignore-scriptsif dependencies are not installed.Add to Codex (use absolute paths to your Node binary and this directory):
codex mcp add trmnl-api -- /absolute/path/to/node /absolute/path/to/trmnl-api-mcp/src/index.jsRun
npm run checkto verify an actual stdio handshake and authenticated device/playlist reads. It prints counts, not account content or credentials.In the desktop app's MCP server settings, restart the MCP connection. Then ask: "Review my TRMNL playlist using trmnl-api."
The server can start and advertise tools before a credential exists; tools return a clear setup error until the key is supplied. It reads the key on every call, so changing the saved key does not require restarting the server.
Other clients may use the included .mcp.json plugin companion after installing dependencies. Environment overrides are TRMNL_ACCOUNT_API_KEY or TRMNL_ACCOUNT_API_KEY_FILE. These are launcher settings, never tool inputs. Direct Codex registration and plugin installation are alternatives; do not enable both copies.
Editing playlists
Inspect the current playlist and relevant schedule before writing; verify the resulting state afterward. Writes are marked as writes in MCP metadata so clients can apply their normal approval policy. Adding write support does not itself change any playlist.
Visibility: use a boolean to show or hide an entry while keeping it configured.
Add: requires the existing plugin setting UUID, as specified by the API. Do not substitute the numeric plugin or playlist item ID. The current list schema does not expose this UUID, so obtain it from the plugin's settings or an existing known value.
Remove: removes the playlist entry and its schedule; hide it if the intention is temporary. There is no undo tool.
Reorder: supply every current item exactly once, including hidden entries. The server reads the latest list before writing and rejects missing, duplicate or foreign IDs. TRMNL also validates the set when applying the change.
Schedule: replaces all windows.
week_schedules: []clears time restrictions so the item is always active, but does not change visibility. Each window has uniqueweek_days(0–6) andstart_time/end_timeinHH:MM. Account timezone is not exposed by these endpoints.
A timeout or invalid response after a write can mean the write succeeded. The server reports that uncertainty and never retries automatically; read current state before deciding whether to retry, especially when adding entries.
Access boundary
The account key itself has broader TRMNL permissions. This server limits access to three read tools and five playlist write tools on a fixed set of paths on https://trmnl.com. It validates method/path combinations and strict tool inputs. There is no generic request tool, arbitrary URL, device-setting write, image download, or account-profile endpoint. Redirects are rejected. Known output fields are selected so unexpected credentials or hardware identifiers are not forwarded. API response text is account data and must not be treated as instructions.
Requests are bounded by a 15-second timeout and 2 MiB response limit. HTTP errors and invalid payloads are reported without returning upstream bodies. No keys or playlist contents are logged. The server has no listening port or persistent background service; the MCP client starts it as needed.
Limits
These endpoints do not expose rendered screen images, mashup section contents, custom item durations, or the account timezone. The plugin's icon is not a preview. Device refresh_interval is a default and does not prove each item's duration. Schedule always_active means no time windows are set, and does not override an item's visible state. The device-specific endpoint documents an empty list for inaccessible devices, so an empty result alone does not prove device ownership.
Verification
npm test checks MCP discovery and stdio negotiation, read/write request routing and payloads, strict inputs, playlist pagination, schedule replacement/clearing, reorder preflight, hidden/mashup items, output filtering, credential-file permissions, and uncertain-write handling. Fixtures are synthetic; only npm run check verifies your account connection. The connection check performs reads only; tests never edit a live playlist.
Sources
TRMNL OpenAPI schema, inspected 2026-09-14. Read routes:
GET /api/devices,GET /api/playlists/items,GET /api/devices/{device_id}/playlist_items,GET /api/playlists/items/{item_id}/schedule. Write routes:POST /api/devices/{device_id}/playlist_items,PATCHandDELETE /api/playlists/items/{id},PUT /api/devices/{device_id}/playlist_items/order,PUT /api/playlists/items/{item_id}/schedule.
Available Tools
8 toolsadd_playlist_itemA
Add an existing plugin instance to a device playlist. plugin_setting_id must be the plugin setting UUID documented by TRMNL, not a numeric plugin ID. This may create another entry if retried; inspect the playlist after any uncertain outcome.
Inputs: device_id (required), plugin_setting_id (required).
get_playlist_item_scheduleARead-onlyIdempotent
Read weekly display windows for a playlist item. week_days uses 0=Sunday through 6=Saturday. Times are returned as stored; the API does not supply timezone. always_active describes schedule windows, not the separate visibility flag.
Inputs: item_id (required).
list_devicesARead-onlyIdempotent
List your TRMNL devices with names, numeric IDs, refresh interval in seconds, sleep settings and last check-in. Credentials and hardware identifiers are excluded.
Inputs: limit, offset.
list_playlist_itemsARead-onlyIdempotent
Read TRMNL playlist items, optionally for one numeric device_id. Returns plugin names, visibility, row_order, group IDs and render timestamps in API order. Does not fetch images or custom durations.
Inputs: limit, offset, device_id.
remove_playlist_itemADestructiveIdempotent
Remove a playlist entry by its item_id. This loses that entry and its schedule; use set_playlist_item_visibility to pause it instead. Read the entry before removal and verify afterward.
Inputs: item_id (required).
reorder_playlist_itemsADestructiveIdempotent
Replace a device playlist ordering. Supply every current playlist item ID exactly once in the desired order, including hidden items. The current list is checked before writing; TRMNL also validates the complete set.
Inputs: device_id (required), playlist_item_ids (required).
replace_playlist_item_scheduleADestructiveIdempotent
Replace ALL weekly display windows for an item. Read the existing schedule first; send all windows to retain. An empty week_schedules array clears time restrictions (always active), not visibility. week_days: 0=Sunday through 6=Saturday; use HH:MM in the account timezone, which this API does not expose.
Inputs: item_id (required), week_schedules (required).
set_playlist_item_visibilityADestructiveIdempotent
Show or hide an existing playlist item without removing it. Inspect the playlist first and verify visibility afterward.
Inputs: item_id (required), visible (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource and action: devices, playlist items, schedules, visibility, and ordering are clearly separated. The read/write schedule pair and visibility vs. removal are described with enough distinction to prevent misselection.
All tools follow a consistent snake_case verb_noun pattern using list/get/set/add/remove/reorder/replace. The naming style is uniform and the resource hierarchy is predictable.
Eight tools cover the device listing and playlist management workflows without redundancy or bloat. The count is well within the ideal range and each tool contributes a distinct playlist lifecycle operation.
The playlist item lifecycle is well covered: add, list, read schedule, update visibility, replace schedule, reorder, and remove. The main gap is that add_playlist_item requires an external plugin_setting_id with no corresponding tool to discover plugin settings, forcing agents to get that ID from outside the server.
Maintenance
Related MCP Connectors
An authenticated remote MCP server for user-owned devices and one-shot capability invocation.
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Local shadow MCP for HVAC, plumbing, electrical, and sewer. Read-only. Not a hosted OS.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to query and manage a Qbee-managed device fleet, offering read tools for device status, files, CVEs, and changes, plus confirmation-gated write operations for configuration, file management, membership, and IAM.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables managing and observing Technitium DNS Server through MCP, including read-only or read-write tool surfaces, scoped bearer authentication, audit logging, and confirmation gates for destructive operations.MIT
- AlicenseAqualityCmaintenanceEnables local stdio MCP clients to list, get, plan, and probe registered devices and their connection endpoints from a private inventory, while keeping credential references rather than secrets in agent responses.4MIT
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to search and manage playlists, library, catalog, discovery, playback, and the Up Next queue across macOS, Windows, and Linux.-