1---
2name: miro-board-connector
3description: Connect to Miro boards, browse content, download images, create boards, draw shapes, connectors, and full diagrams. Use when the user wants to connect Miro, access a Miro board, download mockups from Miro, draw diagrams on Miro, or create architecture/flow diagrams programmatically.
4compatibility: "Runtimes: codex, claude-code, openclaw · OS: linux, darwin"
5allowed-tools: Bash, Read, Write, WebFetch
6---
7 
8# Miro Board Connector
9 
10Connect to a Miro board via OAuth, inspect board items, and download full-size images by spatial region.
11 
12## Bundle Layout
13 
14- `SKILL.md`: primary workflow
15- `scripts/miro_api.py`: OAuth + board inspection + image download helper
16- `CODEX_BOOTSTRAP.md`: Codex-specific activation notes
17- `CLAUDE_BOOTSTRAP.md`: Claude Code-specific activation notes
18- `OPENCLAW_BOOTSTRAP.md`: OpenClaw-specific activation notes
19 
20Run commands from the installed skill directory so relative paths like `scripts/miro_api.py` resolve correctly.
21 
22## Setup Flow
23 
24### Step 1: Check for existing token
25 
26```bash
27test -f ~/.miro-token && echo "Miro token file found" || echo "No Miro token file yet"
28```
29 
30If a token exists, test it:
31 
32```bash
33python3 scripts/miro_api.py test-token
34```
35 
36If valid, skip to **Step 3**. If expired or missing, continue.
37 
38### Step 2: OAuth Setup
39 
40The user needs a Miro app with `boards:read` and `boards:write` scopes. Guide them:
41 
421. Go to https://miro.com/app/settings/user-profile/apps
432. Click **Create new app** (or use an existing one)
443. Set **Redirect URI** to `http://localhost:9876/callback` and click **Add**
454. Check **boards:read** and **boards:write** permissions
465. Save the app
476. Share the **Client ID** and **Client Secret**
48 
49Once you have credentials, run the OAuth flow:
50 
51```bash
52python3 scripts/miro_api.py oauth \
53  --client-id CLIENT_ID \
54  --client-secret CLIENT_SECRET
55```
56 
57This will:
58- Start a local server on port 9876
59- Print an authorization URL for the user to open in their browser
60- Wait for the OAuth callback
61- Exchange the code for an access token
62- Save token metadata to `~/.miro-token`
63 
64Tell the user to open the printed URL in their browser and authorize the app.
65 
66### Step 3: Browse a board
67 
68Get board info:
69 
70```bash
71python3 scripts/miro_api.py board-info --board-url "BOARD_URL"
72```
73 
74List all items with spatial positions and text content:
75 
76```bash
77python3 scripts/miro_api.py list-items --board-url "BOARD_URL"
78```
79 
80This outputs item type, position, size, and text content for every item on the board.
81Use the text content to identify sections, then use positions to find images in those regions.
82 
83### Step 4: Download images
84 
85Download images from a spatial region:
86 
87```bash
88python3 scripts/miro_api.py download-images \
89  --board-url "BOARD_URL" \
90  --region "x_min,y_min,x_max,y_max" \
91  --output-dir /tmp/miro-images \
92  --format original
93```
94 
95Download ALL images on the board:
96 
97```bash
98python3 scripts/miro_api.py download-images \
99  --board-url "BOARD_URL" \
100  --output-dir /tmp/miro-images \
101  --format original
102```
103 
104## Typical Workflow
105 
1061. User says "connect Miro" or "grab images from Miro board"
1072. Check for existing token → if missing, run OAuth setup
1083. User provides board URL
1094. Run `list-items` to see board layout — identify sections by text labels
1105. Identify regions of interest from text item positions
1116. Run `download-images` with `--region` for each area of interest
1127. View downloaded images with the Read tool to understand their content
1138. Use the images as needed (insert into GitHub issues, docs, etc.)
114 
115## Writing: Create boards and draw diagrams
116 
117### Create a board
118 
119```bash
120python3 scripts/miro_api.py create-board --name "My Board" --description "Optional"
121```
122 
123### Draw a diagram from JSON
124 
125Create a JSON file defining shapes and connectors, then draw it on a board:
126 
127```bash
128python3 scripts/miro_api.py draw-diagram \
129  --board-url "BOARD_URL" \
130  --json-file diagram.json \
131  --offset-x 0 --offset-y 0
132```
133 
134**JSON format:**
135 
136```json
137{
138  "title": {"text": "<strong>Diagram Title</strong>", "x": 0, "y": -400, "size": 36, "color": "#fbbf24"},
139  "shapes": [
140    {"id": "api", "content": "<strong>API</strong><br>FastAPI", "x": 0, "y": 0, "w": 180, "h": 70, "fill": "#1e3a5f", "border": "#3b82f6"},
141    {"id": "db", "content": "<strong>Database</strong>", "x": 0, "y": 200, "w": 160, "h": 70, "fill": "#3b1a1a", "border": "#ef4444"}
142  ],
143  "connectors": [
144    {"from": "api", "to": "db", "start_snap": "bottom", "end_snap": "top", "color": "#fbbf24"}
145  ]
146}
147```
148 
149**Shape properties:** `id` (for connectors), `content` (HTML), `x`, `y`, `w`, `h`, `fill`, `border`, `text_color`, `font_size`, `shape` (round_rectangle, rectangle, circle, etc.)
150 
151**Connector snap positions:** `top`, `bottom`, `left`, `right`
152 
153### Create individual items
154 
155```bash
156# Shape
157python3 scripts/miro_api.py create-shape --board-url URL \
158  --content "<strong>Title</strong>" --x 0 --y 0 --width 200 --height 80 \
159  --fill "#1e3a5f" --border "#3b82f6"
160 
161# Text
162python3 scripts/miro_api.py create-text --board-url URL \
163  --content "Header" --x 0 --y -100 --font-size 36 --color "#fbbf24"
164 
165# Connector (use shape IDs from create-shape output)
166python3 scripts/miro_api.py create-connector --board-url URL \
167  --start-id SHAPE_ID --end-id SHAPE_ID --start-snap bottom --end-snap top
168```
169 
170## Notes
171 
172- Requires `python3` and outbound network access to Miro
173- Board URL format: `https://miro.com/app/board/BOARD_ID=/`
174- The `--format original` flag downloads full-size images (not thumbnails)
175- Token metadata is saved to `~/.miro-token` with `0600` permissions
176- When Miro returns a refresh token, the helper auto-refreshes expiring access tokens
177- Images keep their original PNG/JPEG/WebP/SVG file extension when downloaded
178- For write operations, the token must have `boards:write` scope
179