miro-mcp

name

miro-mcp

description

Connect OpenClaw agents to Miro via Model Context Protocol (MCP). Use when generating diagrams, visualizing code, brainstorming board layouts, or integrating Miro into AI-powered design workflows. Supports OAuth 2.1 authentication, 14+ MCP-compatible clients (Cursor, Claude Code, Replit, Lovable, VSCode/Copilot, Gemini CLI, Windsurf, Kiro CLI, Amazon Q, others). Best for design thinking, architecture visualization, project planning, collaborative ideation.

Miro MCP Integration

Quick Start

Miro MCP enables AI agents to read from and write to Miro boards via the Model Context Protocol—an open standard for AI-external system integration. Your agent can generate diagrams, analyze board content, and create code from visual designs.

Prerequisites:

• MCP-capable client (Cursor, Claude Code, Replit, Lovable, VSCode, etc.)
• OAuth 2.1 support in your client
• Active Miro workspace access

Minimal Setup:

1. Add MCP configuration: url: https://mcp.miro.com/
2. Click "Connect" and authenticate via OAuth 2.1
3. Select your Miro team during OAuth flow
4. Start prompting with board URLs

Quick Example:

Prompt: "Summarize the content on this board: https://miro.com/app/board/uXjVGAeRkgI=/"
Result: Agent reads board items and returns a summary

See references/mcp-connection.md for detailed setup instructions per client.

Core Capabilities

Miro MCP supports two primary use cases: diagram generation and code generation.

Diagram Generation

Generate visual diagrams directly on Miro boards from code, PRDs, or text descriptions:

• From Code: Provide repository URLs or code snippets → agent generates architecture/data flow diagrams (UML, flowchart, ERD)
• From PRDs: Share product requirement documents → agent creates visual workflows, user flows, state diagrams
• From Text: Describe a system → agent visualizes it as architecture or sequence diagram
• From GitHub URLs: Agent analyzes GitHub repos and generates architectural diagrams

Tool: Use code_explain_on_board prompt or diagram_create tool with DSL (flowchart, UML class/sequence, ERD).

Code Generation

Generate working code from board content:

• PRD to Code: Board contains product requirements → agent generates documentation + implementation guidance
• Diagram to Code: Architecture diagram on board → agent generates code structure matching the design
• Prototype to Code: Prototype screens on board → agent uses them as implementation guides

Tool: Use code_create_from_board prompt to analyze board and generate docs/code.

Collaboration Features

• Read board context (frames, documents, prototypes, diagrams, tables, images)
• Write new diagrams and documents to boards
• Update existing board content via find-and-replace
• Access board items with cursor-based pagination
• Team-scoped access (MCP app is team-specific)

Supported Clients

Miro MCP has been tested and verified with 14+ MCP-compatible clients:

Client	Method	Notes
Cursor	Config file + OAuth	JSON config in settings
Claude Code	CLI: claude mcp add	Command-line setup
Replit	Web UI + OAuth	Install button integration
Lovable	Web UI + OAuth	Settings → Integrations
VSCode/GitHub Copilot	MCP Registry + OAuth	GitHub MCP Registry link
Windsurf	Config file + OAuth	JSON config in settings
Gemini CLI	CLI setup	Video tutorial available
Kiro CLI	Config file + OAuth	.kiro/settings/mcp.json
Amazon Q IDE	Settings + OAuth	IDE extension config
Claude (Web/Desktop)	Connectors + OAuth	Add connectors in chat
Kiro IDE	Built-in	Native MCP support
Glean	Native	MCP integration ready
Devin	Native	Native MCP support
OpenAI Codex	Protocol-based	Direct MCP access

See references/ai-coding-tools.md for step-by-step setup per client.

Configuration Guidance

OAuth 2.1 Flow Overview

Miro MCP uses OAuth 2.1 with dynamic client registration for secure authentication:

1. Request authorization → Your client constructs an auth URL with client_id, redirect_uri, scope
2. Miro OAuth server → User logs in (or confirms existing session) and consents to requested permissions
3. Team Selection (critical) → User explicitly selects which Miro team the MCP app can access
4. Authorization code → Miro redirects back with authorization_code
5. Token exchange → Your client exchanges code for access_token and refresh_token
6. Board access → Agent includes access_token in API calls to Miro MCP Server

Why team selection matters: MCP is team-scoped. If you reference a board from a different team than the one you authenticated against, you'll get access errors. Simply re-authenticate and select the correct team.

Configuration JSON

Standard JSON configuration (valid for most clients):

{
  "mcpServers": {
    "miro-mcp": {
      "url": "https://mcp.miro.com/",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Rate Limits

• Standard API limits apply to all operations (counted per user across all tool calls)
• Tool-specific limits may be stricter (subject to change)
• context_get is expensive — uses Miro AI credits (only tool that does)
• Optimization: Batch operations, avoid parallel context_get calls, cache frequently accessed content

Enterprise Notes

If you're on Miro Enterprise Plan, your admin must first enable Miro MCP Server in your organization before you can use it. Contact your Miro administrator for enablement.

Common Workflows

Workflow 1: Architecture Diagram from Codebase

User prompt: "Analyze my codebase at ~/dev/myapp and create an architecture diagram on this board: [board-URL]"

Agent steps:
1. Read codebase structure
2. Analyze dependencies and modules
3. Use code_explain_on_board to generate UML diagram
4. Create diagram on Miro board via diagram_create tool

Workflow 2: Code Generation from PRD

User prompt: "This board has our PRD. Generate implementation docs and code guidance."

Agent steps:
1. Use context_explore to find PRD document on board
2. Use context_get to read PRD details
3. Use code_create_from_board prompt
4. Generate docs and implementation guidance
5. Create doc_create items on board with generated content

Workflow 3: Iterative Design Feedback

User prompt: "Summarize this prototype and suggest improvements"

Agent steps:
1. Use context_explore to find prototype screens
2. Use context_get to read screen details/markup
3. Analyze and suggest UX improvements
4. Use doc_create to add feedback document to board

REST API Direct Integration (Automation & Scripting)

Beyond MCP, Miro's REST API enables programmatic board automation via curl/bash scripting. Useful for:

• Bulk board creation and templating
• Automated shape/content generation
• Integration with OpenClaw workflows
• Custom CI/CD board generation
• Template recreation and versioning

Authentication

Use OAuth 2.1 Bearer tokens:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://api.miro.com/v2/...

Tokens obtained via OAuth flow (see OAuth setup in SKILL.md), valid for defined scope.

Board Creation

curl -X POST https://api.miro.com/v2/boards \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Board",
    "description": "Auto-generated template"
  }' | jq '.id'

Shape Creation (Key API Format)

Correct nested structure (discovered via Phase B testing):

curl -X POST https://api.miro.com/v2/boards/{board_id}/shapes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "shapeType": "rectangle",
      "content": "Label text"
    },
    "geometry": {
      "width": 200,
      "height": 100
    },
    "position": {
      "x": 0,
      "y": 0,
      "origin": "center"
    },
    "style": {
      "fillColor": "#3b82f6",
      "borderColor": "#1e40af",
      "borderWidth": 2
    }
  }'

Shape types: rectangle, circle, ellipse, diamond, triangle, pentagon, hexagon, etc.

Text Elements

curl -X POST https://api.miro.com/v2/boards/{board_id}/text \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<b>Bold</b> and <i>italic</i> text",
    "geometry": {
      "width": 300,
      "height": 100
    },
    "position": {
      "x": 0,
      "y": 0,
      "origin": "center"
    },
    "style": {
      "fontSize": 24,
      "color": "#000000",
      "fontFamily": "Arial",
      "textAlign": "center"
    }
  }'

Performance & Scale

• Shape creation speed: ~46ms per shape (tested)
• Batch operations: Can rapidly create 10-20+ shapes per second
• Rate limits: Standard Miro API limits apply (generous for most use cases)
• Script execution: Bash/curl scripts complete full board creation (40+ elements) in < 5 seconds

Template Recreation Pattern

Effective structure for reusable templates:

1. Board creation (metadata)
2. Section headers (color-coded background + text)
3. Content containers (boxes, cards, lists)
4. Visual hierarchy (title → sections → items)
5. Guides (methodology, examples, legends)

See miro-journey-map-recreation.sh in workspace for working example.

Common REST API Endpoints

Method	Endpoint	Purpose
POST	/boards	Create board
GET	/boards/{id}	Get board info
POST	/boards/{id}/shapes	Add shape
POST	/boards/{id}/text	Add text
POST	/boards/{id}/frames	Add frame (container)
GET	/boards/{id}/items	List board items
PATCH	/boards/{id}/items/{id}	Update item
DELETE	/boards/{id}/items/{id}	Delete item

Practical Example: Color-Coded Sections

# Create section background
curl -X POST https://api.miro.com/v2/boards/$BOARD_ID/shapes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"data\": {\"shapeType\": \"rectangle\"},
    \"geometry\": {\"width\": 1400, \"height\": 120},
    \"position\": {\"x\": 0, \"y\": -400, \"origin\": \"center\"},
    \"style\": {\"fillColor\": \"#3b82f6\", \"borderWidth\": 2}
  }"

# Add section title
curl -X POST https://api.miro.com/v2/boards/$BOARD_ID/text \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"<b>Section Title</b>\",
    \"geometry\": {\"width\": 1300, \"height\": 100},
    \"position\": {\"x\": -650, \"y\": -400, \"origin\": \"center\"},
    \"style\": {\"fontSize\": 28, \"color\": \"#ffffff\"}
  }"

Key Learnings

• API structure matters: Correct nesting of data, geometry, position, style is critical
• Bash automation works reliably: No need for SDK when direct API is clear
• Color palettes are key: Consistent colors (Blue, Purple, Green, Yellow) make templates professional
• Positioning uses center origin: (0, 0) is canvas center; adjust x/y for grid layout
• Template scripts are reusable: Save working scripts; iterate on color/content/layout

Resource Links

• Setup by Client: See references/ai-coding-tools.md for detailed step-by-step instructions for all 14 supported clients
• Connection Details: See references/mcp-connection.md for OAuth flow, prerequisites, troubleshooting, and enterprise setup
• MCP Overview: See references/mcp-overview.md for what MCP is, why it matters, security model, and capabilities overview
• Tools & Prompts: See references/mcp-prompts.md for complete tool reference (14 tools), built-in prompts, and rate limit details
• Best Practices: See references/best-practices.md for workflow patterns, common gotchas (team mismatch, OAuth expiry, rate limits), and optimization strategies
• REST API Essentials: See references/rest-api-essentials.md for tool-by-tool API reference, error handling, cost model, and real-world examples
• REST API Automation Scripts: See /Users/bigbubba/.openclaw/workspace/miro-journey-map-recreation.sh for working template recreation example