Miro Management

Use this skill to work with Miro through the REST API.

Quick start

1. Get the user's Miro app client ID, client secret, and redirect URI if using OAuth.
2. Prefer a local redirect URI such as http://127.0.0.1:4000/auth/miro/callback.
3. Use scripts/miro_api.py for OAuth, token refresh, board/item operations, exports, and raw API calls.
4. Start with:
   • auth-url
   • serve-oauth-callback
   • list-boards
   • list-board-items
5. Never bundle client secrets, refresh tokens, or live access tokens into the skill package.

Auth modes

OAuth mode

Use shell environment variables when possible:

$env:MIRO_CLIENT_ID = '...'
$env:MIRO_CLIENT_SECRET = '...'
$env:MIRO_REDIRECT_URI = 'http://127.0.0.1:4000/auth/miro/callback'

Start the callback helper:

python scripts/miro_api.py serve-oauth-callback --port 4000 --token-file .miro/tokens.json

Then generate the authorization URL:

python scripts/miro_api.py auth-url

Open that URL, approve the app, and let the callback helper store the token payload.

Direct token mode

If the user already has a working Miro access token, skip OAuth and use either:

$env:MIRO_ACCESS_TOKEN = '...'
python scripts/miro_api.py list-boards

or a saved token file:

python scripts/miro_api.py list-boards --token-file .miro/tokens.json

Core workflow

1. Confirm access

Use a cheap check first:

python scripts/miro_api.py list-boards --token-file .miro/tokens.json

2. Inspect a board

python scripts/miro_api.py get-board --board-id <id> --token-file .miro/tokens.json
python scripts/miro_api.py list-board-items --board-id <id> --token-file .miro/tokens.json

3. Create or export content

python scripts/miro_api.py create-sticky-note --board-id <id> "Hello from OpenClaw" --token-file .miro/tokens.json
python scripts/miro_api.py create-text --board-id <id> "Roadmap" --token-file .miro/tokens.json
python scripts/miro_api.py create-shape --board-id <id> "API Layer" --token-file .miro/tokens.json
python scripts/miro_api.py create-card --board-id <id> "Task" --token-file .miro/tokens.json
python scripts/miro_api.py export-board-items --board-id <id> --format markdown --output-file board-report.md --token-file .miro/tokens.json

4. Refresh when needed

python scripts/miro_api.py refresh-token --token-file .miro/tokens.json

Common commands

• auth-url — print the OAuth authorization URL
• serve-oauth-callback — run a local callback server and exchange the returned code for tokens
• exchange-code — manually exchange a copied authorization code for tokens
• refresh-token — refresh access using the stored refresh token
• whoami — test token with a lightweight boards call
• list-boards — list accessible boards
• get-board — get board details
• create-board — create a board
• list-board-items — list board items
• export-board-items — export board items to markdown, csv, or json
• create-sticky-note — create a sticky note
• create-text — create a text item
• create-shape — create a shape item
• create-card / update-card — create or update a card item
• create-sticky-note / update-sticky-note — create or update sticky notes
• create-text / update-text — create or update text items
• create-shape / update-shape — create or update shapes
• create-connector — connect two board items
• list-board-members — list board members
• get-webhooks / create-webhook / delete-webhook — manage webhooks
• create-brainstorm-cluster — drop a row of idea sticky notes
• create-kanban-row — create a lightweight kanban-style row
• create-architecture-chain — create connected architecture boxes
• delete-item — delete an item by type path + item id
• preview-write — preview a write request without sending it
• raw — send an arbitrary Miro API request with optional JSON body

Mutation rules

For write calls:

1. Confirm the target board and item IDs.
2. Summarize the exact body and endpoint before sending when the change is not obviously desired.
3. Keep secrets and tokens outside the skill folder.
4. Prefer exporting API results to files instead of dumping giant payloads in chat.
5. Treat live board writes as real external actions, not harmless local tests.

References

Read references/miro-oauth-notes.md for the Miro OAuth flow, token endpoint, redirect URI rules, and safe local storage guidance. Read references/miro-request-examples.md for starter create/export commands and raw request examples.