miro-mcp — Интеграция Miro и AI-агентов через 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](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](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): ```json { "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: ```bash 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 ```bash 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): ```bash 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 ```bash 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 ```bash # 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](references/ai-coding-tools.md) for detailed step-by-step instructions for all 14 supported clients - **Connection Details:** See [references/mcp-connection.md](references/mcp-connection.md) for OAuth flow, prerequisites, troubleshooting, and enterprise setup - **MCP Overview:** See [references/mcp-overview.md](references/mcp-overview.md) for what MCP is, why it matters, security model, and capabilities overview - **Tools & Prompts:** See [references/mcp-prompts.md](references/mcp-prompts.md) for complete tool reference (14 tools), built-in prompts, and rate limit details - **Best Practices:** See [references/best-practices.md](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](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