Skip to main content
Glama

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-mcp

Requires Python 3.12+ (uv handles this).

Claude Code

claude mcp add miro -- uvx --from git+https://github.com/mgh3326/miro-mcp miro-mcp

Claude Desktop / .mcp.json

{
  "mcpServers": {
    "miro": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mgh3326/miro-mcp", "miro-mcp"]
    }
  }
}

Setup: the Miro app and token

  1. Go to https://miro.com/app/settings/ → Your apps → Create new app.

  2. In the app settings, pick the OAuth scopes you need (see the table below).

  3. Click Install app and get OAuth token for your team → copy the token.

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

MIRO_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:read

boards: create/copy/update/delete, items: create/update/delete/upload, tags: attach/detach/create, members: share/update/remove, connectors, groups, docs

boards:write

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_doc bridges)

  • Webhooks — the /v2-experimental/webhooks/* endpoints were retired 2025-12 despite the API introduction still listing them

  • Mermaid/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 them

  • Cursor and offset pagination handled transparently (fetch_all on list tools)

Comparison

Project

Lang

Tools

Notes

miro-mcp (this)

Python

77

full REST surface, profiles, confirm guards, local image/doc upload

olgasafonova/miro-mcp-server (MIT)

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 needed

Live 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 tools
attach_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

share_boardB

Invite users to a board by email (up to 20 per call).

role is one of viewer, commenter, editor, coowner. Grants access — requires confirm=true.

Inputs: emails (required), board_id (required), role, confirm, +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

    C2.8/5.0

    Scored across 77 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 npm
      2
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible LLMs to interact with Miro whiteboards to manage boards, create and manipulate shapes, and organize content through grouping tools.
      -
    • 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