miro-mcp
Provides tools for interacting with the Miro REST API v2, enabling management of boards, board members, items such as sticky notes, shapes, cards, frames, images, and documents, plus connectors, groups, tags, mindmap nodes, and board exports.
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., "@miro-mcp create a sticky note saying 'Sprint kickoff' on my roadmap board"
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.
miro-mcp
An open-source MCP server for the Miro REST API v2.
Python 3.12+, the official mcp SDK (FastMCP), httpx, stdio transport.
Why
The hosted Miro MCP connector can hit daily call caps on free plans. The REST
API instead rate-limits per minute (our token showed x-ratelimit-limit: 100000 credits/min), and this server covers the full public REST surface —
including local image file upload, which the hosted connector lacks.
Related MCP server: Miro MCP Server
Install
# run straight from git (uvx caches it)
uvx --from git+https://github.com/mgh3326/miro-mcp miro-mcp
# or from PyPI (placeholder — not published yet)
uvx miro-mcpRequires Python 3.12+ (uv handles this).
Claude Code
claude mcp add miro -- uvx --from git+https://github.com/mgh3326/miro-mcp miro-mcpClaude Desktop / .mcp.json
{
"mcpServers": {
"miro": {
"command": "uvx",
"args": ["--from", "git+https://github.com/mgh3326/miro-mcp", "miro-mcp"]
}
}
}Setup: the Miro app and token
Go to https://miro.com/app/settings/ → Your apps → Create new app.
In the app settings, pick the OAuth scopes you need (see the table below).
Click Install app and get OAuth token for your team → copy the token.
Either export it or put it in the env file:
export MIRO_ACCESS_TOKEN=...
# or, persisted:
mkdir -p ~/.config/miro-mcp
echo 'MIRO_ACCESS_TOKEN=...' > ~/.config/miro-mcp/miro.envMIRO_ENV_FILE overrides the env file location. The token is never printed
or logged.
Scopes per tool group
Tool group | Required scope |
boards: get/list, items: get/list/search, tags: get, members: get, token context |
|
boards: create/copy/update/delete, items: create/update/delete/upload, tags: attach/detach/create, members: share/update/remove, connectors, groups, docs |
|
export jobs | Enterprise Discovery token (separate, see below) |
identity:read/team:*/admin scopes are not used — this server only
needs board scopes, plus the Enterprise Discovery token for export jobs.
Tool profiles
Set MIRO_MCP_PROFILE:
full(default) — all 77 tools.essential— a ~15-tool subset for cheaper prompts:whoami,list_boards,get_board,list_items,get_item,search_items,create_sticky_note,create_shape,create_text,create_card,create_frame,create_connector,upload_image,attach_tag,delete_item.
Tools
Boards & members
list_boards, get_board, create_board, copy_board, update_board,
delete_board† · list_board_members, get_board_member, share_board†,
update_board_member†, remove_board_member†
Items
list_items (type/parent/cursor/fetch_all), get_item, search_items,
get_items_by_tag, update_item_position, delete_item†,
bulk_create_items (≤20 via POST /items/bulk), bulk_update_items,
bulk_delete_items†
Create + update per type: create_/update_ × sticky_note, shape,
text, card, app_card, frame, embed, document (URL + file
upload), image (URL + local file upload), code_widget (experimental)
Connectors, groups, tags
list/get/create/update/delete_connector† · create_group, list_groups,
get_group, get_group_items, update_group, ungroup† ·
list_tags, create_tag, get_tag, update_tag, delete_tag†,
attach_tag, detach_tag†, get_item_tags
Mindmap (experimental)
list/get/create/delete_mindmap_node — uses /v2-experimental endpoints.
Docs (doc format)
create_doc (markdown/html), get_doc, delete_doc†,
replace_doc† — docs are create/read/delete-only in REST; replace_doc
is a labeled delete+recreate (new item id).
Export
get_board_thumbnail (any plan) · list_board_export_jobs,
create_board_export_job (SVG/PDF/HTML), get_board_export_job_status,
get_board_export_job_results — Enterprise plan only, using the
Discovery access token from Settings → Enterprise Integrations.
Misc
whoami — token context (user, team, scopes).
† destructive or sharing-changing tools require confirm=true; without it
they return a confirmation_required error and make no HTTP call. Confirmed
deletes are logged (item ids, never the token).
Not in the REST API (gaps)
The hosted Miro MCP has capabilities that the public REST API does not, so this server honestly reports them as unavailable instead of faking:
Comments, tables, kanban, timeline — no REST endpoints
Doc update — REST is create/read/delete only (
replace_docbridges)Webhooks — the
/v2-experimental/webhooks/*endpoints were retired 2025-12 despite the API introduction still listing themMermaid/DSL diagram creation, canvas SVG read/write — not in REST; see the roadmap
Resilience
429 → honors
Retry-After, else adaptive exponential backoff (consecutive throttles back off harder, reset on success)502/503/504 → retried with exponential backoff (max 5 retries total)
x-ratelimit-*headers are surfaced in tool results when Miro sends themCursor and offset pagination handled transparently (
fetch_allon list tools)
Comparison
Project | Lang | Tools | Notes |
miro-mcp (this) | Python | 77 | full REST surface, profiles, confirm guards, local image/doc upload |
Go | ~110 | the coverage reference — incl. Mermaid→diagram, audit, tool search | |
k-jarzyna/mcp-miro (Apache-2.0) | TS | ~40 | endpoint shapes reference |
Official Miro MCP (hosted) | — | ~15 | comments/tables/kanban via private APIs; daily caps on free plan |
Roadmap (v2, planned)
Mermaid / DSL → native diagram with local layout
Canvas SVG read & write
HTTP transport (currently stdio only)
Short response caching, circuit breaker
Development
uv sync --group dev
uv run ruff check . && uv run ruff format .
uv run mypy src
uv run pytest -q # mocked HTTP (respx), no token neededLive smoke test once you have a token:
uv run scripts/smoke.py --board-id <BOARD_ID> [--image shot.png]License
MIT — see LICENSE. All code is original; no third-party code was ported (the referenced projects were used for endpoint coverage and design research only).
Available Tools
77 toolsattach_tagB
Attach a tag to an item (cards/stickies: max 8 tags). Changes are not reflected in realtime — refresh the board to see them.
Inputs: tag_id (required), item_id (required), board_id (required). Returns: result
bulk_create_itemsA
Create up to 20 items in one call.
Each entry follows the Miro bulk schema: {"type": "sticky_note", "data": {...}, "style": {...}, "position": {"x":..,"y":..}, "geometry": {...}, "parent": {"id": frame_id}}. Types: app_card,
card, document, embed, image (URL), shape, sticky_note, text.
Inputs: items (required), board_id (required). Returns: result
bulk_delete_itemsB
Delete many items concurrently. Requires confirm=true; ids are
logged when confirmed.
Inputs: board_id (required), item_ids (required), confirm. Returns: result
bulk_update_itemsA
Update many items concurrently (client-side batch; no bulk-update endpoint exists in REST).
Each entry: {"item_id": str, "item_type": str?} plus any of
data, style, position, geometry, parent dicts sent
verbatim. With item_type the typed endpoint is used (e.g.
sticky_notes); without it, the generic position/parent endpoint.
Returns per-item ok/error results.
Inputs: updates (required), board_id (required). Returns: result
copy_boardC
Copy an existing board, optionally renaming or moving it to a team.
Inputs: board_id (required), name, team_id, description. Returns: result
create_app_cardC
Create an app card (widget card linked to an app).
status: disconnected, connected or disabled. fields is a list
of field values shown on the card. border_shape: round or square.
Inputs: x (required), y (required), title (required), board_id (required), +8 more. Returns: result
create_boardC
Create a new board. team_id targets a team; project_id
targets a Miro space (projects were renamed to spaces).
Inputs: name (required), team_id, project_id, description. Returns: result
create_board_export_jobA
Start a board export job (up to 1000 boards).
ENTERPRISE PLAN ONLY — requires a Discovery access token. format
is SVG (default), HTML, or PDF. Returns the job id; poll
get_board_export_job_status then download via
get_board_export_job_results (results live for 14 days).
Inputs: org_id (required), board_ids (required), format. Returns: result
create_cardC
Create a card. due_date is ISO 8601 (2026-12-31).
Inputs: x (required), y (required), title (required), board_id (required), +8 more. Returns: result
create_code_widgetC
Create a code widget (syntax-highlighted code block). EXPERIMENTAL.
Inputs: x (required), y (required), code (required), board_id (required), +6 more. Returns: result
create_connectorC
Connect two items. caption adds a text label. Caps like
end_stroke_cap="arrow" control arrowheads; stroke_style is
normal, dotted or dashed.
Inputs: board_id (required), end_item_id (required), start_item_id (required), color, +8 more. Returns: result
create_docB
Create a doc format item on the board.
content_type is markdown or html. Docs cannot be edited
via REST after creation — see replace_doc.
Inputs: x (required), y (required), content (required), board_id (required), +2 more. Returns: result
create_document_from_urlC
Add a document item (PDF, etc.) to the board from a URL.
Inputs: x (required), y (required), board_id (required), document_url (required), +2 more. Returns: result
create_embedC
Create an embed item from a URL. mode: inline or modal.
Inputs: x (required), y (required), url (required), board_id (required), +9 more. Returns: result
create_frameC
Create a frame. show_content hides/shows children on the canvas.
format accepts custom; frame type defaults to freeform.
Inputs: x (required), y (required), title (required), board_id (required), +5 more. Returns: result
create_groupC
Group items together. item_ids are the items to group.
Inputs: board_id (required), item_ids (required). Returns: result
create_image_from_urlC
Create an image item from a public URL.
Inputs: x (required), y (required), url (required), board_id (required), +3 more. Returns: result
create_mindmap_nodeB
Create a mind map node (text type). EXPERIMENTAL.
With parent_node_id the node becomes a child of that node;
without it Miro creates/extends the root structure.
Inputs: content (required), board_id (required), x, y, +2 more. Returns: result
create_shapeC
Create a shape. shape is one of: rectangle, round_rectangle,
circle, triangle, rhombus, parallelogram, trapezoid, pentagon, hexagon,
octagon, wedge_round_rectangle_callout, star,
flow_chart_predefined_process, cloud, cross, can, right_arrow,
left_arrow, left_right_arrow, left_brace, right_brace. Colors are hex
strings like #ff0000.
Inputs: x (required), y (required), board_id (required), color, +11 more. Returns: result
create_sticky_noteC
Create a sticky note. content accepts simple HTML (<p>,
<b>, <br/>...). fill_color is a Miro palette name
(gray, light_yellow, yellow, orange, light_green, green, dark_green,
cyan, light_pink, pink, violet, red, light_blue, blue, dark_blue,
black).
Inputs: x (required), y (required), content (required), board_id (required), +6 more. Returns: result
create_tagB
Create a tag. fill_color (required by Miro) is a colour name:
red, light_green, cyan, yellow, magenta, green, blue, gray, violet,
dark_green, dark_blue or black.
Inputs: title (required), board_id (required), fill_color. Returns: result
create_textC
Create a standalone text item. content accepts simple HTML.
Inputs: x (required), y (required), content (required), board_id (required), +7 more. Returns: result
delete_boardA
Delete a board permanently. Requires confirm=true.
Inputs: board_id (required), confirm. Returns: result
delete_connectorC
Delete a connector. Requires confirm=true.
Inputs: board_id (required), connector_id (required), confirm. Returns: result
delete_docC
Delete a doc format item. Requires confirm=true.
Inputs: item_id (required), board_id (required), confirm. Returns: result
delete_itemA
Delete any single item. Requires confirm=true; the item id is
logged when confirmed.
Inputs: item_id (required), board_id (required), confirm. Returns: result
delete_mindmap_nodeB
Delete a mind map node. EXPERIMENTAL. Requires confirm=true.
Inputs: item_id (required), board_id (required), confirm. Returns: result
delete_tagA
Delete a tag from the board. Requires confirm=true.
Inputs: tag_id (required), board_id (required), confirm. Returns: result
detach_tagB
Remove a tag from an item. Requires confirm=true.
Inputs: tag_id (required), item_id (required), board_id (required), confirm. Returns: result
get_boardB
Get full details of one board (name, owner, links, sharing policy).
Inputs: board_id (required). Returns: result
get_board_export_job_resultsA
Get the download links of a finished board export job.
ENTERPRISE PLAN ONLY — requires a Discovery access token.
Inputs: job_id (required), org_id (required). Returns: result
get_board_export_job_statusB
Get the status of a board export job.
ENTERPRISE PLAN ONLY — requires a Discovery access token.
Inputs: job_id (required), org_id (required). Returns: result
get_board_memberC
Get one board member (role, type).
Inputs: board_id (required), member_id (required). Returns: result
get_board_thumbnailA
Get the board's thumbnail image URL.
Reads the board's picture field — a small rendered preview, not a
full-fidelity export. For PDF/SVG use the Enterprise export job tools.
Inputs: board_id (required). Returns: result
get_code_widgetC
Get one code widget. EXPERIMENTAL.
Inputs: item_id (required), board_id (required). Returns: result
get_connectorC
Get one connector (start/end items, captions, style).
Inputs: board_id (required), connector_id (required). Returns: result
get_docC
Get a doc format item including its markdown/html content.
Inputs: item_id (required), board_id (required). Returns: result
get_groupC
Get one group with the items it contains.
Inputs: board_id (required), group_id (required). Returns: result
get_group_itemsB
List the items that belong to a group (cursor-paginated).
Inputs: board_id (required), group_id (required), limit, cursor. Returns: result
get_itemB
Get the full JSON of one item (data, style, position, geometry, parent, timestamps).
Inputs: item_id (required), board_id (required). Returns: result
get_items_by_tagC
List items carrying a given tag (offset-paginated).
Inputs: tag_id (required), board_id (required), limit, offset. Returns: result
get_item_tagsC
List the tags attached to an item.
Inputs: item_id (required), board_id (required). Returns: result
get_mindmap_nodeC
Get one mind map node. EXPERIMENTAL.
Inputs: item_id (required), board_id (required). Returns: result
get_tagC
Get one tag.
Inputs: tag_id (required), board_id (required). Returns: result
list_board_export_jobsB
List board export jobs for an organization.
ENTERPRISE PLAN ONLY — requires a Discovery access token.
Inputs: org_id (required), limit, offset. Returns: result
list_board_membersB
List members of a board (offset-paginated). Set fetch_all to
walk all pages.
Inputs: board_id (required), limit, offset, fetch_all. Returns: result
list_boardsA
List boards visible to the token.
Offset-paginated. query filters on board name/description,
owner accepts e.g. me or a user id, sort e.g. default,
alphabetically, last_opened, last_created, last_modified.
Set fetch_all to walk all pages (careful on large accounts).
Inputs: sort, limit, owner, query, +4 more. Returns: result
list_code_widgetsC
List code widget items. EXPERIMENTAL: uses the
/v2-experimental endpoints which may change.
Inputs: board_id (required), limit, cursor. Returns: result
list_connectorsB
List connectors on a board (cursor-paginated).
Inputs: board_id (required), limit, cursor. Returns: result
list_groupsB
List all groups on a board (cursor-paginated).
Inputs: board_id (required), limit, cursor. Returns: result
list_itemsA
List items on a board in a compact shape (id, type, x, y, size, parent, text).
type filters to one item type (app_card, card, doc_format, document,
embed, frame, image, shape, sticky_note, text). parent_item_id
lists children of a frame. Cursor-paginated; fetch_all walks all
pages.
Inputs: board_id (required), type, limit, cursor, +2 more. Returns: result
list_mindmap_nodesC
List mind map nodes on a board. EXPERIMENTAL — the /v2-experimental API may change.
Inputs: board_id (required), limit, cursor. Returns: result
list_tagsB
List all tags on a board (cursor-paginated).
Inputs: board_id (required), limit, cursor. Returns: result
remove_board_memberB
Remove a member from a board. Requires confirm=true.
Inputs: board_id (required), member_id (required), confirm. Returns: result
replace_docA
Replace a doc's content — implemented as read + delete + create because REST has no doc update endpoint.
The new doc gets a NEW item id; the old id stops existing. Preserves
position, geometry, parent and content type (unless overridden).
Requires confirm=true.
Inputs: content (required), item_id (required), board_id (required), confirm, +1 more. Returns: result
search_itemsB
Search items by text content (client-side scan of titles/content).
Scans up to max_pages x 50 items. Returns compact matches.
Inputs: query (required), board_id (required), type, max_pages, +1 more. Returns: result
ungroupA
Dissolve a group (items stay on the board). Requires
confirm=true.
Inputs: board_id (required), group_id (required), confirm. Returns: result
update_app_cardC
Update an app card's data, style, position or parent.
Inputs: item_id (required), board_id (required), x, y, +9 more. Returns: result
update_boardC
Rename a board or change its description.
Inputs: board_id (required), name, description. Returns: result
update_board_memberB
Change a board member's role (viewer, commenter, editor, coowner).
Requires confirm=true.
Inputs: role (required), board_id (required), member_id (required), confirm. Returns: result
update_cardC
Update a card's data, style, position or parent.
Inputs: item_id (required), board_id (required), x, y, +9 more. Returns: result
update_code_widgetD
Update a code widget. EXPERIMENTAL.
Inputs: item_id (required), board_id (required), x, y, +5 more. Returns: result
update_connectorC
Update a connector's endpoints, caption or style.
Inputs: board_id (required), connector_id (required), color, caption, +9 more. Returns: result
update_documentC
Update a document item (replace its URL, retitle, move).
Inputs: item_id (required), board_id (required), x, y, +3 more. Returns: result
update_embedC
Update an embed item's data, position or parent.
Inputs: item_id (required), board_id (required), x, y, +10 more. Returns: result
update_frameC
Update a frame's title, visibility, style, size or position.
Inputs: item_id (required), board_id (required), x, y, +5 more. Returns: result
update_groupB
Replace a group's membership entirely with a new set of items.
A new group id is assigned by Miro on update.
Inputs: board_id (required), group_id (required), item_ids (required). Returns: result
update_imageC
Update an image item (swap URL, retitle, move/resize).
Inputs: item_id (required), board_id (required), x, y, +4 more. Returns: result
update_item_positionB
Move an item on the canvas or reparent it into/out of a frame.
Works on any item type. parent_id set to a frame id nests the item;
use "none" semantics per Miro docs to detach (send parent omitted
and change position instead).
Inputs: item_id (required), board_id (required), x, y, +1 more. Returns: result
update_shapeC
Update a shape's content, style, position or parent.
Inputs: item_id (required), board_id (required), x, y, +12 more. Returns: result
update_sticky_noteC
Update a sticky note's content, style, position or parent.
Inputs: item_id (required), board_id (required), x, y, +7 more. Returns: result
update_tagA
Rename a tag or change its color. Note: tag changes via REST are not reflected on the board in realtime — refresh the board to see them.
Inputs: tag_id (required), board_id (required), title, fill_color. Returns: result
update_textC
Update a text item's content, style, position or parent.
Inputs: item_id (required), board_id (required), x, y, +12 more. Returns: result
upload_documentC
Upload a document file from the local disk (PDF, DOCX, PPTX, XLSX, CSV; max ~30 MB).
Inputs: x (required), y (required), board_id (required), file_path (required), +2 more. Returns: result
upload_imageC
Upload a local image file to the board (PNG/JPG/SVG, max 6 MB).
This is a real multipart upload — the main gap vs. the hosted Miro connector.
Inputs: x (required), y (required), board_id (required), file_path (required), +4 more. Returns: result
whoamiA
Show the context of the current access token.
Returns the token type, the user the token belongs to, the team it was installed on, and the granted scopes. Useful to verify auth before other calls. Requires no board.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 77 tools
Most tools have a distinct resource/action target, and descriptions clarify overlaps such as generic get_item versus type-specific get_doc/get_group. However, the many per-type create/update tools plus generic bulk and generic get/list tools create some selection ambiguity for agents.
The set overwhelmingly follows a snake_case verb_noun convention (create_board, update_sticky_note, bulk_delete_items). Minor deviations like whoami and ungroup are readable but not fully consistent with the pattern.
77 tools is an extreme mismatch for a coherent agent-facing toolset; the surface is inflated by per-item-type CRUD variants and bulk/generic alternatives. This creates substantial selection burden even if individual tools are useful.
The surface covers boards, members, tags, groups, connectors, docs, many item types, exports, and auth, with broad CRUD coverage. Minor gaps remain, such as no update operation for mind map nodes and some resource access relying on generic item tools.
Related MCP Connectors
Read and edit Teamwide whiteboards: boards, notes, shapes, arrows, images, PNG/PDF export.
Read and update Markboard kanban boards: cards, checklists, labels, comments and files.
Read and change the AIrboard whiteboards of your human: items, frames, comments, renders, uploads.
Create and update Boords projects, scripts, storyboards, frames and comments from your AI app.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive access to the Miro REST API v2 for advanced board management, content creation, and team collaboration. It supports over 40 tools for managing board items like sticky notes and shapes, alongside bulk operations and organizational features.23 npm2Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables MCP-compatible LLMs to interact with Miro whiteboards to manage boards, create and manipulate shapes, and organize content through grouping tools.-
- 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