Connect your own AI agent to TRMNL. Claude, ChatGPT, Cursor and other MCP clients can read and change your devices, playlists and plugins, or edit one private plugin's markup, from wherever you already work.
This is different from the AI Agent inside TRMNL, which builds plugins in your browser. The MCP server lets an agent you bring yourself do the same work, and more, from outside the dashboard.
There are two ways in. If you are not sure, connect your account. You can limit it to a single plugin when you sign in.
Whole account. Sign in with your TRMNL account, no key needed. The agent reaches what you allow when you sign in.
One plugin. An MCP API key from a private plugin's settings. The agent reaches that plugin's markup and nothing else. Use it for a client that can't sign in, or to hand one plugin to someone else.
Prerequisites
A TRMNL account
An MCP client, such as Claude Code, Claude (web or desktop), ChatGPT on a paid plan, Cursor or Codex
Step 1 - Add the server to your agent
The server lives at https://trmnl.com/mcp. How you add it depends on the client.
Claude Code
Install the TRMNL plugin. It adds the server and the TRMNL agent skill, which teaches Claude the framework rules for markup:
/plugin marketplace add usetrmnl/trmnl-agent-skills
/plugin install trmnl@trmnl-agent-skills
Prefer the server on its own? Run claude mcp add --transport http trmnl https://trmnl.com/mcp instead. That registers it for the current folder only. Add --scope user to use it everywhere. The Claude Code desktop app reads the same setup.
Claude on the web and desktop
Go to Customize, then Connectors, and choose Add custom connector. Paste https://trmnl.com/mcp and add it. On a Team or Enterprise plan, an Owner adds it once under Organization settings, then Connectors.
ChatGPT
Custom connectors need a paid plan and developer mode. Open Settings, then Apps & Connectors, then Advanced settings, and turn on Developer mode. Back in Apps & Connectors, choose Create, paste https://trmnl.com/mcp and pick OAuth.
Cursor
Add this to ~/.cursor/mcp.json, then restart Cursor: {"mcpServers": {"trmnl": {"url": "https://trmnl.com/mcp"}}}
Other agents
Codex, Gemini CLI, VS Code and most other clients take https://trmnl.com/mcp as an HTTP, or streamable HTTP, server. The client has to support MCP sign-in. TRMNL is also listed in the official MCP Registry as com.trmnl/trmnl.
Step 2 - Sign in and choose what it may do
The first time the agent connects, TRMNL opens in your browser and asks what it may do. In Claude Code, run /mcp in a session and pick trmnl to start this. The browser tab may go blank afterwards. That is normal, the agent already has what it needs.
You tick what the agent may do:
Read your devices and their logs, playlists, plugin settings and private plugin files
Content, to change your markup, plugin settings, playlists and mashups, install recipes and push images
Devices, to change your device settings and identify a device
Delete plugin settings and playlist items, and clear a device playlist
Profile, to view your profile information
Apps, to install apps and manage them, including fleet pushes and room bookings
Delete, Profile and Apps start unticked, so an agent can't remove anything unless you say so. You can also limit the agent to some of your devices and plugin settings.
Step 3 - You're done!
Ask the agent for something. "List my devices." "What's on the kitchen display's playlist?" "Show my calendar on weekdays from 9 to 5 and Reddit in the evenings."
The agent's TRMNL tools come in pairs, one that only reads and one that makes changes. Most clients run the reads without asking and check with you before a change.
To see what you've connected, go to Account, then Developer, then Connected agents. Each agent shows when it was last active. Edit access changes which devices and plugin settings it reaches, and Revoke signs it out straight away. To change what it can do, revoke it and connect again. A connection unused for 30 days signs out by itself, and your tool asks you to sign in again next time.
One plugin with an MCP API key
A key reaches one private plugin: its markup, screenshots, merge variables, logs and data refreshes, plus recipe search and the design system guide. It can't see your devices, playlists or other plugins.
Open a private plugin's settings and click Save once if it is new. Find MCP API Key and choose Generate MCP Key. The key starts with ps_mcp_.
In Claude Code, run claude mcp add --transport http trmnl https://trmnl.com/mcp --header "Authorization: Bearer YOUR_KEY"
In other clients, use https://trmnl.com/mcp?api_key=YOUR_KEY as the server address. MCP client config, under the key, has a ready-made snippet.
Keys are only offered on private plugins, and not on a read-only copy of someone else's recipe. Treat the key like a password. Revoke Key on the same page cuts the agent off, and you can generate a new one.
Agent skills
The TRMNL agent skills are the same rules our own AI Agent follows: the framework, Liquid, and what works on an ePaper screen. They work without the MCP server too, so an agent can write good markup on your machine and you paste it in. They're packaged for Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot and opencode.
Limits
Each connection may send 60 requests a minute.
A change that renders a screen, such as a preview or a refresh, spends from your account's hourly render allowance. The dashboard shares the same allowance.
Every action is an operation of the TRMNL API. The authentication reference covers keys, OAuth and scopes in full.
Troubleshooting
The client says "Needs authentication" - The server is added but you haven't signed in yet. In Claude Code, run /mcp and pick trmnl. Other clients show a Connect button.
An action answers 403 and names a capability - You didn't tick it when you signed in. Revoke the agent under Connected agents and connect again, ticking what it needs.
An action answers 403 and names a device or plugin setting - You limited the agent. Widen it with Edit access under Connected agents.
The agent says the account has used its renders for the hour - The hourly render allowance is spent. Wait for the hour to pass, then try again. Retrying sooner doesn't help.
The server answers 401 with your account API key - The account API key from Account, then Developer, is for the REST API and does not work with the MCP server. Sign in, or use a plugin's MCP API Key.
The agent can't see your devices - It's connected with a plugin key, which reaches one plugin only. Connect it to the whole account instead.
Password fields come back empty - That's on purpose. The server never hands secrets such as passwords or API keys to an agent.
ChatGPT signs in but the connector fails afterwards - This was fixed on October 2, 2026. Remove the connector and create it again.
Related
AI Agent, TRMNL's own plugin builder in the browser
Developer Apps, for building your own app on the TRMNL API