miro-board-mcp
Turns a Markdown document (including Mermaid flowcharts and Wardley maps) into a laid-out Miro board: validates and previews the resulting frames, elements and connectors with a spec hash, then builds the board on a new or allowlisted existing board only after explicit human confirmation. Also lists the frames of an allowed board and can build from a YAML spec with exact coordinates when free placement is needed.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
miro-board-mcp
An MCP server that lets an agent turn a Markdown document into a Miro board: check it, preview it, and build it only after a person has said yes.
Built in November 2026 with Claude Code as co-developer.
Problem
A workshop board in Miro takes hours to lay out by hand. An agent can write the content quickly, but when it also writes coordinates, it gets them wrong: in the first two end-to-end runs of this server, an agent drew diagonal axes because it read line offsets as end points, and stacked four frames on top of each other because it read the frame spacing as a gap. And whatever an agent builds in Miro, it builds in a shared space that people work in.
Related MCP server: Miro MCP Server
What it does
A board is one Markdown document. The server places every frame and element; the agent writes no coordinates.
Markdown | On the board |
| board name |
| one frame, in document order |
paragraphs, | a text block at the top of the frame |
bullet or numbered list | one sticky note per item |
| shapes and connectors, laid out with dagre |
| a Wardley map; pipelines are drawn as bands |
tables, images, other code | not drawn; validation names the line |
The same document renders in any Markdown viewer that supports Mermaid, so the source stays readable without Miro.
Tool | What it does |
| Checks a document without building anything: errors and warnings with their Markdown line, texts that will not fit, elements outside their frame. Read-only. |
| Runs the real builder against a dry-run transport: frames in build order with position, size and element count, Miro API calls, estimated time, and a |
| Builds on a new board, or on an existing board from an allowlist. |
| Lists the frames of an allowed board with position and size, to check the result. |
Resource | Content |
| the document format, the supported Mermaid syntax, the rules |
| a complete, valid board document for a fictional workshop |
| advanced: JSON Schema of the generator's YAML format |
| advanced: the same workshop as a YAML spec with coordinates |
Prompt | Arguments | Does |
|
| guide → document → validate → preview → ask → build after the user's explicit yes |
All tools also take an optional spec parameter instead of document: a YAML spec with exact coordinates, for the rare board that needs them.
Example
From examples/code-review-basics.md, a fictional 45-minute workshop:
## From pull request to merge
```mermaid
flowchart LR
open([Open]) --> review[Review]
review -->|changes requested| fix[Fix]
fix --> review
review -->|approved| merge([Merge])
```preview_board on the whole document:
Preview of "Code Review Basics": 6 frames, 49 elements (incl. 6 title bars), 9 connectors, 64 Miro API calls (about 42 s).
1. Code Review Basics: 2 elements incl. title bar, 1600 x 900 at (800, 450)
2. Welcome: 5 elements incl. title bar, 1600 x 900 at (2700, 450)
...
5. Where our review practice stands: 25 elements incl. title bar, 1920 x 1280 at (8560, 640)
spec_hash: sha256:2daefb10...
Show this list to the user. Only after the user confirms, call build_board with dry_run: false and confirm_hash set to spec_hash.A mistake comes back with its line and the fix:
Invalid: 1 error.
- line 7: wardley-beta could not read "component Zugänge [0.3, 0.7]": unexpected character: ->ä<-.
A name with umlauts or one of : , ? needs double quotes, e.g. component "Zugänge" [0.30, 0.70].Safety
The server writes to a shared workspace on behalf of a model, so every write is gated:
A person approves every write.
build_boardis a dry run unless called withdry_run: falseand thespec_hashthatpreview_boardreturned for exactly this document. Any change after the preview changes the hash.Only allowed boards. It creates new boards, and touches existing ones only if their ids are in
MIRO_MCP_ALLOWED_BOARD_IDS(or it created them in this process). It cannot delete or change anything that exists.Limits. Input size, frames, elements, API calls per build, builds per process and build time are capped; a build stops between frames on cancellation and at once on 401, 403 or 404, and returns what exists.
Secrets. The Miro token comes only from the environment, is never logged and never appears in a result.
No external content. Images and embeds need an https host from
MIRO_MCP_ALLOWED_URL_HOSTS(none by default); YAML!includeis off; alias bombs are stopped before parsing.stdio discipline. stdout carries JSON-RPC only; all logging goes to stderr.
The reasoning behind each of these is in docs/design.md.
Quick start
Requires Node.js 22.18 or later.
git clone --recurse-submodules <this repository>
cd miro-board-mcp
npm install
npm run build
npm testmiro-board-builder, the generator this server builds on, is a git submodule in vendor/, pinned to one commit. If you cloned without --recurse-submodules, run git submodule update --init before npm install.
Validation and preview need no token and no network. Try them with the MCP Inspector:
npx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/listConfiguration
Copy .env.example and set the variables in the environment of the server process:
Variable | Needed for |
|
|
| optional: team for new boards |
| optional: existing boards the server may use |
| optional: hosts for images and embeds |
With 1Password, keep only a reference in an env file (MIRO_ACCESS_TOKEN=op://Vault/Item/field) and start the server through op run --no-masking --env-file=...; --no-masking keeps stdio untouched. Claude Code waits 30 seconds for a server to start; set MCP_TIMEOUT=120000 if the 1Password approval takes longer.
Claude Code
claude mcp add miro-board --scope user -- node /absolute/path/to/miro-board-mcp/dist/server.jsThen ask: "Create a Miro board for a 60-minute retrospective", or run the prompt template from the / menu.
Claude Desktop
In claude_desktop_config.json, with absolute paths (Claude Desktop does not use your shell's PATH), here with the token from 1Password:
{
"mcpServers": {
"miro-board": {
"command": "/opt/homebrew/bin/op",
"args": [
"run",
"--no-masking",
"--env-file=/absolute/path/to/.env.op",
"--",
"/opt/homebrew/bin/node",
"/absolute/path/to/miro-board-mcp/dist/server.js"
]
}
}
}The tools then appear in the tools menu of a new chat.
Limits
Frames are placed in one row; inside a frame, blocks stack from the top. There is no free placement in a document; use
specfor that.Mermaid support covers
flowchartandwardley-beta. Flowcharts are parsed by the officialmermaidpackage, which needs a DOM in Node; a jsdom window provides it, at the cost of about 130 MB of dependencies.evolveon a part of a pipeline is not drawn, because Mermaid does not draw it either.The server never updates or deletes existing items. A second build adds a second copy.
Miro's rate limit makes large boards slow: about 0.65 seconds per item.
How this was built
What existed before: miro-board-builder, my generator that builds a Miro board from a YAML description through the REST API.
What is new: this MCP server, built in November 2026. It started with the generator's YAML as input. Three end-to-end runs with an agent and a fault test with 20 deliberate mistakes shaped it: the coordinate errors of the first two runs led to layout warnings and then to Markdown with Mermaid as the input, so that the server computes every position; the fault test led to findings that name the line of their cause. The generator gained two library options (no !include for untrusted input; stop on cancellation and on fatal Miro errors) and schema descriptions.
Claude Code was co-developer: it drafted much of the code, the tests and the documentation, and ran the end-to-end tests in separate sessions. I defined the problem, decided the design (docs/design.md), reviewed every phase before the next one started, and approved every write to Miro.
Licence
MIT, see LICENSE.
Related tools
miro-board-builder: describe a Miro board in YAML and build it through the REST API (the generator this server builds on)
wardley-map-builder: render Wardley maps from YAML to PNG or onto a Miro board
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Markdown notes and whiteboards your AI agent can read and write.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Create, read and live-edit visual boards, Kanban plans, Gantt timelines and diagrams with AI agents.
Set up human approval for your AI agents' tool calls.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables agents to search official Mermaid diagram syntax documentation and validate Mermaid diagram code before presenting it to users, ensuring syntactically correct flowcharts, sequence diagrams, class diagrams, and other Mermaid visualizations.902 npmMIT
- 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
- AlicenseNot gradedqualityDmaintenanceEnables AI agents and users to render Mermaid diagram code blocks into embedded SVGs within Obsidian notes locally, while preserving reversible synchronization with sidecar .mmd files.1MIT