Skip to main content
Glama

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 SDK

Features

  • Read cheaply — get_board_info gives 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_items lays items out as a grid, row or column; group_items and reorder_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 with create_table (grouped shapes) and drawings as SVG images.

  • See the result — capture screenshots 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 setup

setup does everything and is safe to re-run (it repairs and upgrades):

  1. registers with Claude Code if it is installed (node + absolute path: fast start, offline, no Windows npx quirks),

  2. installs a background service that starts at login and starts it now (Windows Startup folder / macOS LaunchAgent / systemd user unit),

  3. opens the Miro install page (skipped if a board is already connected) — pick the team that owns your boards,

  4. 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

miro-bridge-mcp setup

install, repair, or finish an update

miro-bridge-mcp check

OK/FAIL for service, login start, board, app version, board menu

miro-bridge-mcp config

config snippets for other AI apps

miro-bridge-mcp uninstall

remove the login service and Claude Code entry (then npm rm -g miro-bridge-mcp)

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

get_board_info

Overview: counts by type, frames, focus, app-version warning. Call first.

get_focus / set_focus

Read / set the user's focus.

get_items

Read items by type, ids or parentId (frame). Compact; full: true for raw SDK fields.

get_selection

What the user has selected right now.

create_items

Create many items in one call; images accept path to a local file. Rolled back on error.

update_items

Merge props into items (style is merged).

delete_items

Delete by id (connectors removed with their shape count as alreadyGone).

arrange_items

Grid / row / column layout.

zoom_to

Move the viewport to items.

group_items

Group items, or ungroup a group.

reorder_items

Bring to front / send to back.

create_table

Draw a table as a grid of shapes (native Miro tables are not in the SDK).

capture

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

No Miro board connected

Is the app installed in this board's team? Is a board open?

Connects only after F5

The background service isn't running: run miro-bridge-mcp setup once.

Board menu actions missing

Beta feature: run check for the reason. Use the app icon meanwhile.

Brave doesn't connect

Settings → Privacy → allow Localhost access for miro.com (or drop Shields on miro.com).

isn't inside a parent frame

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.

capture fails

Windows only; the Miro window must not be minimized (it can be behind other windows).

port 7788 is used by another program

Set MIRO_BRIDGE_PORT and the app URL to a free port.

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:write

In 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.1 only. 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 tools
arrange_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_itemsA
Destructive

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_infoA
Read-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_focusA
Read-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_itemsA
Read-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_selectionB
Read-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_toB
Read-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

    A3.7/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to programmatically interact with a Miro board through the Miro API, supporting operations like creating items, updating positions, and managing connectors.
      16
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      3
      MIT