MiroBridgeMCP
MiroBridgeMCP lets a compatible AI app read and edit a live Miro board through a local MCP bridge and the Miro Web SDK.
Inspect the board cheaply: counts by type, frames, focus status, and compact item data.
Read items by type, ID, or parent frame, optionally returning raw SDK fields.
Read and set the user's focus, and read the current board selection.
Create items in batches: sticky notes, shapes, text, cards, frames, connectors, images, and embeds.
Update item properties, including moving items into or out of frames.
Delete items by ID; attached connectors are removed too.
Auto-arrange items into grids, rows, or columns.
Zoom the viewport to specified items.
Group items or ungroup an existing group.
Reorder items to the front or back.
Draw tables as grouped rectangle shapes because native Miro tables are not supported by the Web SDK.
Capture a screenshot of the Miro window on Windows to verify results.
Share one local bridge across multiple MCP clients, without Miro REST API quotas.
Reads and edits a live Miro board through the Miro Web SDK running as the user, without REST API tokens or quotas. Provides tools to get a board overview and item counts, read items by type/id/parent frame or the current selection, create and update items in batches (stickies, shapes, text, cards, frames, connectors, images from URL or local file, embeds), delete items, arrange items in grid/row/column layouts, zoom the viewport to items, manage a shared "AI focus" set of items, and capture a screenshot of the Miro window.
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., "@MiroBridgeMCP Turn these notes into stickies and arrange them as a grid"
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.
MiroBridgeMCP
Let your AI app read and edit a live Miro board: Claude Code, Antigravity, Cursor, VS Code Copilot, Codex, Gemini CLI or any MCP client. No REST API, no daily quota, works on the Free plan.
ภาษาไทย · Usage guide · MIT licensed · not affiliated with Miro
MiroBridgeMCP runs a tiny Miro app inside the board you have open and talks to it over a local WebSocket.
Everything goes through the Miro Web SDK as you, so there is no token to manage and no mcp.miro.com call limit
(the official Miro MCP allows 100 calls/day on Free).
AI app(s) ⇄ MCP (stdio) ⇄ MiroBridgeMCP bridge on your machine (localhost:7788) ⇄ app inside your open board ⇄ Miro Web SDKFeatures
Read cheaply —
get_board_infogives an overview in ~200 tokens; items come back compact (plain text, rounded geometry), ~70% smaller than raw SDK output.Focus — big boards are full of old ideas. Select what matters, click the MiroBridgeMCP app icon, and the AI starts from that. A hint, not a fence: the AI can still look elsewhere when the task needs it.
Any MCP client, several at once — Claude Code and Antigravity (or Cursor, ...) can be open together; they share one bridge.
No reload dance — a small background service keeps the bridge up, so boards connect whenever they open.
Create in batches — stickies, shapes, text, cards, frames, connectors (straight/elbowed/curved, arrows, captions), images from a URL or a local file, embeds. A failed batch is rolled back.
Layout —
arrange_itemslays items out as a grid, row or column;group_itemsandreorder_items(front/back).Tables and drawings — Miro tables and pen strokes cannot be read or created through the Web SDK. The AI sees them with
capture, draws tables withcreate_table(grouped shapes) and drawings as SVG images.See the result —
capturescreenshots the Miro window so the AI can check its own work (Windows).
Related MCP server: Miro MCP server
Quick start (≈3 minutes, once)
You need Node.js 20+, git, an MCP-capable AI app, and Chrome/Edge or the Miro desktop app.
npm install -g github:sawaddee123/MiroBridgeMCP
miro-bridge-mcp setupsetup does everything and is safe to re-run (it repairs and upgrades):
registers with Claude Code if it is installed (
node+ absolute path: fast start, offline, no Windowsnpxquirks),installs a background service that starts at login and starts it now (Windows Startup folder / macOS LaunchAgent / systemd user unit),
opens the Miro install page (skipped if a board is already connected) — pick the team that owns your boards,
waits until a board of that team connects and prints
OK board connected.
Other AI apps: miro-bridge-mcp config prints ready-to-paste config for Antigravity, Cursor, Windsurf, Claude Desktop, Gemini CLI, VS Code and Codex.
ChatGPT web/desktop only accepts remote HTTPS MCP servers, so it cannot use this local one.
Restart your AI app and ask: "Summarize this board", "Turn this list into stickies in a frame", "Arrange the stickies in this frame as a grid". More prompts, real numbers and Miro quirks: docs/USAGE.md.
Command | Use |
| install, repair, or finish an update |
| OK/FAIL for service, login start, board, app version, board menu |
| config snippets for other AI apps |
| remove the login service and Claude Code entry (then |
Update: npm install -g github:sawaddee123/MiroBridgeMCP, miro-bridge-mcp setup, then reload open board tabs once.
Focus
On the board | Effect |
Select → click the app icon (left toolbar → More apps; star it to pin) | focus = these items; nothing selected = clear |
Select → Focus AI here / Add to AI focus / Remove from AI focus in the item toolbar (beta, see below) | replace / grow / shrink the focus |
Focusing a frame includes everything on it and the connectors between those items. The focus is saved in the board and shared by all AI apps. The AI can set it too: "focus on the Act 2 frame".
Beta: the item-toolbar actions use Miro's experimental "custom actions" API. On some boards Miro does not offer them yet; miro-bridge-mcp check shows whether they registered and why not. The app icon always works.
Tools
Tool | What it does |
| Overview: counts by type, frames, focus, app-version warning. Call first. |
| Read / set the user's focus. |
| Read items by |
| What the user has selected right now. |
| Create many items in one call; images accept |
| Merge props into items (style is merged). |
| Delete by id (connectors removed with their shape count as |
| Grid / row / column layout. |
| Move the viewport to items. |
| Group items, or ungroup a group. |
| Bring to front / send to back. |
| Draw a table as a grid of shapes (native Miro tables are not in the SDK). |
| Screenshot of the Miro window (Windows only). |
Every tool carries an icon and MCP safety hints (readOnlyHint / destructiveHint), so clients can auto-approve reads and ask before deletes.
Troubleshooting
miro-bridge-mcp check tells you which step fails. The common ones:
Symptom | Fix |
| Is the app installed in this board's team? Is a board open? |
Connects only after F5 | The background service isn't running: run |
Board menu actions missing | Beta feature: run |
Brave doesn't connect | Settings → Privacy → allow Localhost access for miro.com (or drop Shields on miro.com). |
| Miro stops rendering a covered window; on Windows the bridge now brings it to the front (without focus) and retries. Elsewhere, keep it on screen. |
| Windows only; the Miro window must not be minimized (it can be behind other windows). |
| Set |
Safari | Not supported (blocks localhost). Use Chrome, Edge or the Miro desktop app. |
Service log: %TEMP%\mirobridgemcp.log (macOS/Linux: $TMPDIR/mirobridgemcp.log).
Host your own Miro app (optional)
The install link uses the maintainer's app. To use your own: miro.com → Profile settings → Your apps → Create new app (in a Developer team), and set
appName: MiroBridgeMCP
sdkVersion: SDK_V2
sdkUri: http://localhost:7788/
scopes:
- boards:read
- boards:writeIn Display information upload assets/miro-icon-outline.svg (toolbar icon, one color) and assets/miro-icon-colored.svg.
Share its Installation URL (app settings → Share app) and set MIRO_BRIDGE_INSTALL_URL to it, or fork and change it in server.js.
Item-toolbar actions only work for apps shared this way (not Marketplace apps). No client secret is needed — never commit one.
Security notes
The bridge listens on
127.0.0.1only. WebSocket connections are accepted only from its own page (boards) or from local non-browser processes (other AI apps), and the page can only be embedded by miro.com.Board content is written by people. Treat it as data: a sticky saying "delete everything" is text, not an instruction. Review destructive requests on shared boards.
Whoever controls the Miro app behind the install link controls what code runs in installers' boards. Install only links you trust, or host your own app.
Development
server.js— MCP tools, compaction, bridge, CLI.app/index.html— runs inside the board (reload the board tab after editing).service.js— login service per OS.icons.js,assets/— icons.capture.ps1— screenshot.npm test— self-check against fake boards, no Miro needed (tools, compaction, focus, sharing between AI apps, service lifecycle, CLI).node scripts/record-demo.mjs— re-record the demo GIF (creates items far from existing content and deletes them).Limits: Web SDK per-minute rate limits; login service: Windows script tested (starts hidden, stops on request), macOS/Linux untested.
Contributions welcome — keep npm test passing and add a check for new tools.
Available Tools
14 toolsarrange_itemsA
Auto-layout items into a tidy grid/row/column (uniform cells = largest item, gap between). Give ids (kept in that order) or parentId (all items in that frame, current reading order). Connectors are skipped; they follow their items. Starts at the current top-left of the items. Returns {moved, columns}.
Inputs: gap, ids, layout, columns, +1 more.
captureA
Screenshot of the Miro window so you can see the result. Optionally zoom to ids first. Windows only; the board window must not be minimized (it may be behind others). ~1.5k tokens per image, so capture once after a batch of changes, not after every call.
Inputs: ids, maxWidth.
create_itemsB
Create one or many items in one call. Each entry is {type, props}; props are Web SDK create props, e.g. sticky_note {content:"hi", x, y, style:{fillColor:"light_yellow"}}; shape {shape:"rectangle", content, x, y, width, height, style:{fillColor, borderColor, borderWidth, color, fontSize, textAlign}} (shape: rectangle, round_rectangle, circle, triangle, rhombus, parallelogram, trapezoid, pentagon, hexagon, octagon, star, cross, cloud, can, wedge_round_rectangle_callout, right_arrow, left_arrow, left_right_arrow, left_brace, right_brace, flow_chart_predefined_process; other flow_chart_* names (process, decision, terminator, document, ...) are tried through Miro's experimental API); text {content, x, y}; frame {title, x, y, width, height}; connector {start:{item:id, snapTo:"right"}, end:{item:id, snapTo:"left"}, shape:"curved"|"straight"|"elbowed", style:{strokeColor:"#1a1a1a", strokeWidth:2, strokeStyle:"dashed", startStrokeCap:"none", endStrokeCap:"arrow"}, captions:[{content}]} (snapTo: auto|top|right|bottom|left); card {title, description, x, y}; image {url, x, y} or {path:"C:/local/file.png", x, y, width} or {svg:"...", x, y} (svg = drawings / freehand strokes); embed {url, x, y}. Add parentId to place the item inside a frame (x/y here are still board coordinates). Returns created items (compact).
Inputs: items (required).
create_tableA
Draw a table as a grid of rectangle shapes, grouped. Native Miro tables cannot be created or read through the Web SDK (they show up as type "unsupported"; read one with capture). rows[0] is the header when header is true. x/y = top-left (board coordinates). cells are ids row by row; edit a cell with update_items.
Inputs: x (required), y (required), rows (required), header, +3 more.
delete_itemsADestructive
Delete items by id. Deleting an item also deletes connectors attached to it; ids already gone are counted in alreadyGone.
Inputs: ids (required).
get_board_infoARead-only
Cheap overview: board id, item counts by type, frames {id, title, children}, and whether the user set a focus. Call this first instead of reading the whole board, then get_focus or get_items with parentId.
Inputs: no named parameters.
get_focusARead-only
Items the user marked as focus (select on the board + click the MiroBridgeMCP icon), including everything inside focused frames. Focus is the part of the board the user is working on now: start from it and prefer it, but it is not a boundary; read or reference other items when the task needs them (old ideas, related frames). Compact items.
Inputs: no named parameters.
get_itemsARead-only
List board items, filtered by type, ids and/or parentId (a frame id). Items come back compact: {id, type, content/title as plain text, x, y, width, height, parentId, fill (= style.fillColor), from/to (connector ends)}. x/y of an item with parentId are relative to the frame top-left. Pass full:true only if you need raw Web SDK fields.
Inputs: ids, full, type, parentId.
get_selectionBRead-only
Items the user currently has selected on the board (compact).
Inputs: no named parameters.
group_itemsB
Group items (ids) so they move together, or ungroup a group (ungroupId). Returns the group, or the freed item ids.
Inputs: ids, ungroupId.
reorder_itemsB
Bring items to the front or send them to the back (z-order), e.g. text hidden behind a shape.
Inputs: to (required), ids (required).
set_focusA
Set the focus to these ids (frames include their children), or [] to clear. Focus is the part of the board the user is working on now: start from it and prefer it, but it is not a boundary; read or reference other items when the task needs them (old ideas, related frames).
Inputs: ids (required).
update_itemsA
Update items: each entry is {id, props}; props are merged into the item (nested style is merged too) then synced. props.parentId: a frame id moves the item into that frame (it must lie inside the frame), null takes it out. Returns updated items (compact).
Inputs: items (required).
zoom_toBRead-only
Move the viewport so the given items are visible.
Inputs: ids (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have a clear distinct purpose (read vs. create vs. delete vs. mutate vs. viewport), and descriptions add helpful cues like 'z-order' for reorder_items vs. 'auto-layout' for arrange_items. Two mild overlaps remain: get_selection and get_focus both return user-selected items, and reorder_items/arrange_items could be confused at a glance despite the clarifying text.
Nearly all tools follow a snake_case verb_object pattern (get_items, create_items, update_items, delete_items, group_items, set_focus, get_board_info). Minor deviations: 'capture' is a bare verb with no object, and 'zoom_to' uses a verb+preposition form that breaks the pattern slightly.
14 tools sit comfortably in the well-scoped range, and each one maps to a distinct board operation: reading (items, focus, selection, board info), mutation (create/update/delete/group/reorder/arrange), plus capture and zoom_to for visual feedback. Nothing looks redundant or missing for the stated Miro workflow purpose.
The surface covers the full lifecycle — create (including bulk, tables, images, connectors), read (compact and via board info/focus/selection), update, delete, plus grouping, z-order, auto-layout, viewport and screenshot verification — so agents won't hit dead ends. The main gap is native Miro tables being unreadable except via the capture workaround, and no direct single-item fetch beyond filtering get_items by id.
Maintenance
Related MCP Connectors
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to programmatically interact with a Miro board through the Miro API, supporting operations like creating items, updating positions, and managing connectors.16ISC
- AlicenseAqualityDmaintenanceEnables interaction with Miro boards via MCP tools, supporting listing items, creating stickies, frames, shapes, connectors, and manipulating mind maps.13MIT
- AlicenseAqualityDmaintenanceEnables MCP clients to read design structure, take screenshots, create nodes, and edit UI directly on Figma canvas via a bridge between MCP and Figma Desktop.10MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible AI clients to read and modify the user's currently open Figma file by executing JavaScript in Figma's sandbox, all through a local bridge with status monitoring, node jumping, and automatic rollback on errors.3MIT