Miro MCP server
Allows interaction with a Miro REST API, providing tools for board management, mind maps, sticky notes, frames, shapes, connectors, and item manipulation on Miro boards.
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 server list all sticky notes on board uXjVGnXi5V0="
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 server (custom)
TypeScript Model Context Protocol server that talks to the Miro REST API v2 (plus experimental mind map endpoints under v2-experimental). It exposes tools for listing board items, board metadata, native mind maps, creating stickies, frames, shapes, and connectors, and updating, moving, or deleting items. The host (Cursor, Claude Desktop, or another MCP client) spawns this process over stdio; the model decides when to call each tool from the tool descriptions.
Requirements: Node.js 18+, a Miro OAuth access token with boards:read and boards:write.
Setup
1. Clone the repository
git clone https://github.com/DChuhin/miro-mcp-server.git
cd miro-mcp-serverUse your fork’s URL if you cloned from elsewhere.
2. Install dependencies and build
npm install
npm run buildThe MCP entrypoint is dist/index.js. Re-run npm run build after changing TypeScript sources if your client runs the compiled file (see Cursor / Claude below).
3. Miro token and board ID
Token (required for the server to call Miro)
In Miro, open the Developer / Your apps area and create an app.
Enable scopes
boards:readandboards:write.Complete the OAuth flow to obtain an access token (see Miro OAuth).
You can keep secrets out of the shell by copying the example env file:
cp .env.example .env
# Edit .env and set MIRO_TOKEN=...For Cursor and Claude Desktop, the most reliable approach is to put MIRO_TOKEN in the MCP config’s env block (see below). The spawned process may not load .env unless the client sets the working directory to the project root.
Never commit .env or paste tokens into chat.
Board ID (required in normal use)
Tools take a board_id argument. The model needs the board ID whenever you ask for board-specific work. Find it in the board URL: the segment after /board/ (example shape: uXjVGnXi5V0=). Mention it explicitly in prompts, for example: “On board uXjV…, list sticky notes.”
The server does not read a default board from the environment for MCP tool calls. MIRO_BOARD_ID is only useful for the optional integration test script (see Development).
Cursor
Complete setup steps 1–3 (clone,
npm install,npm run build, obtain a token).Open Cursor Settings → MCP (or edit the MCP config file directly). Cursor commonly uses
~/.cursor/mcp.json.
Example (replace the path with the absolute path to this repo on your machine):
{
"mcpServers": {
"miro-custom": {
"command": "node",
"args": ["/absolute/path/to/miro-mcp-server/dist/index.js"],
"env": {
"MIRO_TOKEN": "your_miro_oauth_token_here"
}
}
}
}Alternative (development): point args at tsx and the TypeScript entry so you can skip npm run build while iterating:
{
"mcpServers": {
"miro-custom": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/miro-mcp-server/src/index.ts"],
"env": {
"MIRO_TOKEN": "your_miro_oauth_token_here"
}
}
}
}Reload MCP servers or restart Cursor after saving the config.
Claude Desktop
Complete setup steps 1–3 (clone,
npm install,npm run build, obtain a token).Edit Claude Desktop MCP configuration (location varies by OS; search for
claude_desktop_config.jsonin Claude’s documentation).Under
mcpServers, add the same shape as in Cursor, using the absolute path todist/index.js:
{
"mcpServers": {
"miro-custom": {
"command": "node",
"args": ["/absolute/path/to/miro-mcp-server/dist/index.js"],
"env": {
"MIRO_TOKEN": "your_miro_oauth_token_here"
}
}
}
}Restart Claude Desktop after changes. Enable the miro-custom server in the app if your client lists MCP servers per conversation.
Sanity check (optional)
npm startThis runs the MCP server on stdio. On its own it will appear to “hang”; that is normal. You normally do not run it in a terminal unless you are debugging—the editor spawns it once MCP is configured.
Related MCP server: Miro MCP Server
Using the agent (LLM + tools)
After the MCP server is connected in Cursor or Claude:
Open a chat that has MCP tools enabled for this server.
Give the board ID (from the board URL) when you ask for board-specific work.
The model can call tools such as
get_board_info,list_board_items,list_mindmap_nodes,create_mindmap_node,delete_mindmap_node,create_sticky_note,create_frame,create_connector,update_item_content,move_item, anddelete_item.
Example prompts:
“Call
get_board_infofor boarduXjV…and summarize the board.”“List all sticky notes on board
…, then add a yellow sticky at (100, -50) with the text ‘Review Q2’.”“Create a frame titled ‘Backlog’ and two stickies inside it connected by a curved connector.”
“On board
…, calllist_mindmap_nodes, then add a child node under id…with text ‘New branch’.”
Mind maps use Miro’s native widget (text nodes; connectors are managed by Miro). Use list_mindmap_nodes / create_mindmap_node / delete_mindmap_node—not shapes plus create_connector.
Why coordinates? In the desktop app, + uses Miro’s internal layout; the experimental REST create mind map node API still expects a position and defaults omitted coordinates to (0,0), which stacks every node. That endpoint does not expose the same auto-placement as the UI, so this server computes x/y unless you pass them explicitly. Parent positions for that math come from list_mindmap_nodes (or a direct experimental mind map node read), not from generic GET /v2/boards/.../items/{id}—nested mind map nodes can report widget-local coordinates there, which would shift deeper children incorrectly.
Layout rule (this tool): Left-to-right mind maps only—the root is leftmost; every child is placed to the right of its parent (parent.x + offset). Siblings of the same parent share that X column and are spaced vertically using layout_sibling_index (0, 1, 2, …)—pass it when creating several children in a row because list_mindmap_nodes can lag. The create payload must stay within MindmapCreateRequest only. Overview: Mind map (Experimental).
Example hierarchy — use each create response’s id (or list_mindmap_nodes) as the next parent_node_id:
Order |
|
|
|
1 | Center | (omit = root) | (omit) |
2 | node1 | Center’s id |
|
3 | node2 | Center’s id |
|
4–7 | nebula, quartz, velvet, ember | node1’s id |
|
8–11 | cascade, prism, lotus, raven | node2’s id |
|
Optional: set root position with x / y on the first call (e.g. 1160, 0).
The agent chooses tools based on their registered names and descriptions; you do not call the REST API yourself in normal use.
Development
Run the server with tsx (no separate build step):
npm run devEnsure MIRO_TOKEN is set (for example via .env in the project root). The dev server still uses stdio, so it is mainly useful with an MCP client attached or for quick sanity checks.
Optional integration test against a real board (creates and then deletes test widgets unless SKIP_CLEANUP=1):
export MIRO_TOKEN='your_token'
export MIRO_BOARD_ID='board_id_from_url'
npx tsx scripts/miro-integration-test.tsCompile manually when not using npm run dev with tsx:
npm run buildProject layout
Path | Role |
| MCP server entry, registers tools |
| HTTP client for |
|
|
|
|
| Create stickies, frames, shapes, connectors |
| Update content, move, delete |
| Optional real-board test |
Troubleshooting
401 / token errors: Regenerate or refresh the OAuth token; confirm
boards:readandboards:write.Server not listed: Fix JSON in the MCP config, use absolute paths, restart the app.
Old behaviour after edits: Run
npm run buildagain if the client usesdist/index.js.
License
MIT
Available Tools
13 toolscreate_connectorA
Creates a connector (line/arrow) between two existing items on the board. Use this to draw relationships in diagrams (e.g. link shapes, stickies, or cards). You need the item IDs of both endpoints — call list_board_items first if you don't have them. Native mind map hierarchies use create_mindmap_node instead of manual connectors.
Inputs: board_id (required), end_item_id (required), start_item_id (required), color, +3 more.
create_frameA
Creates a named frame (a rectangular container) on the board. Frames are used to group related content into sections. Use this before populating a new area with items so they can be logically grouped. Returns the frame ID which you can then use to place items inside it.
Inputs: x (required), y (required), title (required), board_id (required), +3 more.
create_mindmap_nodeA
Creates a native Miro mind map node (experimental REST API). Layout rule for this tool: left-to-right mind maps only—the root is leftmost; every child is always placed to the RIGHT of its parent (positive X offset); multiple children of the same parent are spaced vertically (layout_sibling_index 0,1,2,…). The Miro desktop + button does not send coordinates because the app runs its own layout engine; the REST create endpoint still requires a position object and defaults missing coordinates to (0,0), which stacks nodes—see https://developers.miro.com/reference/create-mindmap-nodes-experimental —so this server computes x/y for you unless you pass explicit x/y. MindmapCreateRequest allows only data.nodeView, position, geometry, parent. When creating several children under one parent in quick succession, list_mindmap_nodes often lags—pass layout_sibling_index per child so Y offsets differ. Example: root Center (optional x/y); under Center—node1 with layout_sibling_index 0, node2 with 1 (both to the right of Center); under node1—four leaves with indices 0–3; under node2—four leaves with 0–3. Insert short delays between calls for rate limits. Overview: https://developers.miro.com/docs/mind-maps
Inputs: content (required), board_id (required), x, y, +3 more.
create_shapeA
Creates a geometric shape (rectangle, rounded rectangle, circle, pill, etc.) on the board with optional text inside. Use this to create labels, containers, or visual nodes in diagrams and flows. For Miro's native mind map widgets (hierarchy, auto connectors), use list_mindmap_nodes and create_mindmap_node instead.
Inputs: x (required), y (required), shape (required), board_id (required), +7 more.
create_sticky_noteA
Creates a sticky note on a Miro board at a specified position. Use this to add ideas, tasks, labels, or annotations. You can optionally place it inside a frame. Choose a color that matches the semantic meaning (e.g. yellow for ideas, red for blockers, green for done).
Inputs: x (required), y (required), color (required), content (required), +3 more.
delete_itemB
Deletes an item from the board permanently. Use with caution. Use this to clean up placeholder content or remove outdated items. Requires item ID.
Inputs: item_id (required), board_id (required).
delete_mindmap_nodeA
Deletes a native mind map node and all of its descendant nodes (experimental REST API). Use list_mindmap_nodes to find node ids. See https://developers.miro.com/docs/mind-maps
Inputs: node_id (required), board_id (required).
get_board_infoA
Returns metadata about a Miro board: its name, description, creation date, owner, and dimensions. Use this at the start of a session to confirm you are working on the correct board before reading or modifying content.
Inputs: board_id (required).
list_board_itemsA
Lists all items on a Miro board, optionally filtered by type. Use this to understand what is already on the board before creating or modifying anything. Returns item IDs, types, positions, and text content.
Inputs: board_id (required), type.
list_mindmap_nodesA
Lists native Miro mind map widget nodes on a board using the experimental REST API.
This is not the same as generic board items from list_board_items: mind maps are
text-based nodes with hierarchy and auto-managed connectors. Use this to read an
existing mind map (node IDs, parents, text, positions when the API returns them).
Each node includes style (widget: nodeColor/border, shape, fontSize) and
node_view_style (text color, fillOpacity, fontSize) when Miro returns them—
either may be null if the API omits fill/stroke data. Limitations: https://developers.miro.com/docs/mind-maps
Inputs: board_id (required).
move_itemA
Moves an existing item to a new position on the board. Use this to reorganize layout, avoid overlaps, or align items visually. Coordinates are absolute board coordinates (center of board is 0,0).
Inputs: x (required), y (required), item_id (required), board_id (required).
update_item_contentA
Updates the text content of an existing sticky note, shape, or text item on the board. Use this to correct or improve existing content without moving or deleting the item. Requires the item ID — call list_board_items first if you don't have it.
Inputs: content (required), item_id (required), board_id (required).
update_mindmap_nodeA
Updates the HTML/text content of an existing native mind map node (experimental PATCH).
Use this instead of update_item_content: generic GET /items/{id} does not support mindmap_node.
Content is stored in data.nodeView (same shape as create). Example: <p>Title. <a href="https://tracker.yandex.com/QUEUE-1">QUEUE-1</a></p>.
Inputs: content (required), node_id (required), board_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct item type or action, and the descriptions explicitly clarify the tricky boundary between generic items (update_item_content, delete_item) and native mind map nodes (update_mindmap_node, delete_mindmap_node). Minor ambiguity remains around whether delete_item/move_item apply to mind map nodes, but overall boundaries are clear.
All 13 tools follow a strict snake_case verb_noun pattern (list_board_items, create_sticky_note, update_mindmap_node, delete_item), with a consistent `<verb>_<resource>` structure across both generic and mind-map-specific tools. No convention mixing.
13 tools is well-scoped for a board-manipulation server, with each tool earning its place by covering a distinct item type or lifecycle operation. No redundant or filler tools.
Covers solid create/read/update/delete across standard items (sticky, shape, frame, connector) and mind map nodes. Minor gaps exist: no way to discover/list available boards to obtain a board ID, and no update for connector endpoints or item styling/geometry beyond content.
Related MCP Connectors
Official Miro MCP server - Supports context to code and creating diagrams, docs, and data tables.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for controlling Miro whiteboards with AI assistants. Create and manage stickies, shapes, frames, connectors, and more.8833MIT
- 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
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables Claude AI to programmatically create and manipulate Miro boards via the Miro API with OAuth2 authentication. Supports 14 tools for board, item, and connector operations.-