Skip to main content
Glama
Miro MCP server
by DChuhin

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

Use your fork’s URL if you cloned from elsewhere.

2. Install dependencies and build

npm install
npm run build

The 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)

  1. In Miro, open the Developer / Your apps area and create an app.

  2. Enable scopes boards:read and boards:write.

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

  1. Complete setup steps 1–3 (clone, npm install, npm run build, obtain a token).

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

  1. Complete setup steps 1–3 (clone, npm install, npm run build, obtain a token).

  2. Edit Claude Desktop MCP configuration (location varies by OS; search for claude_desktop_config.json in Claude’s documentation).

  3. Under mcpServers, add the same shape as in Cursor, using the absolute path to dist/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 start

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

  1. Open a chat that has MCP tools enabled for this server.

  2. Give the board ID (from the board URL) when you ask for board-specific work.

  3. 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, and delete_item.

Example prompts:

  • “Call get_board_info for board uXjV… 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 …, call list_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

content

parent_node_id

layout_sibling_index

1

Center

(omit = root)

(omit)

2

node1

Center’s id

0

3

node2

Center’s id

1

4–7

nebula, quartz, velvet, ember

node1’s id

0, 1, 2, 3

8–11

cascade, prism, lotus, raven

node2’s id

0, 1, 2, 3

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 dev

Ensure 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.ts

Compile manually when not using npm run dev with tsx:

npm run build

Project layout

Path

Role

src/index.ts

MCP server entry, registers tools

src/miro-client.ts

HTTP client for https://api.miro.com/v2

src/tools/items.ts

list_board_items, get_board_info

src/tools/mindmap.ts

list_mindmap_nodes, create_mindmap_node, delete_mindmap_node (experimental API)

src/tools/create.ts

Create stickies, frames, shapes, connectors

src/tools/mutate.ts

Update content, move, delete

scripts/miro-integration-test.ts

Optional real-board test


Troubleshooting

  • 401 / token errors: Regenerate or refresh the OAuth token; confirm boards:read and boards:write.

  • Server not listed: Fix JSON in the MCP config, use absolute paths, restart the app.

  • Old behaviour after edits: Run npm run build again if the client uses dist/index.js.


License

MIT

Available Tools

13 tools
create_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

    A4/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers