JHamidun Miro
Два независимых пути к доскам. Сначала определи, какой нужен — они покрывают РАЗНОЕ.
Выбор пути
| Задача | Путь | Почему |
|---|---|---|
| Прочитать/суммаризовать доску, понять что на ней | MCP | context_get, context_explore — единственный способ получить смысловую выжимку |
| Создать пачку стикеров/фреймов/шейпов, разложить layout | MCP | layout_create — DSL, вся раскладка одним вызовом |
| Диаграмма (flowchart, mindmap, UML, sequence, ERD) | MCP | diagram_create из DSL |
| Док, таблица, код-виджет, прототип из HTML | MCP | Специализированные инструменты, в REST их нет |
| Комментарии: прочитать, ответить, закрыть | MCP | comment_* |
| Коннекторы (стрелки между элементами) | REST | ❗ MCP их НЕ умеет |
| Теги, группы, app cards, embeds | REST | ❗ MCP их НЕ умеет |
| Точечное редактирование одного элемента по id | REST | MCP правит через find-and-replace по DSL |
| Скриптовая пакетная обработка, свои пайплайны | REST | Не тратит дневную MCP-квоту |
Правило: сложил доску через MCP → соединил элементы стрелками через REST. Это типичный совместный сценарий.
Путь 1 — MCP (основной)
Конфиг сервера едет вместе с паком — в ~/.claude/settings.json → mcpServers:
"miro": { "type": "http", "url": "https://mcp.miro.com/" }
Не видишь miro в выводе /mcp — значит блок не доехал: допиши его туда сам и перезапусти сессию.
Авторизация (один раз): /mcp в сессии → выбрать miro → войти в браузере → выбрать команду.
Из терминала: claude mcp login miro. Сбросить: claude mcp logout miro.
Доступен на всех планах. Free/Starter/Business/Educational — включён по умолчанию. Enterprise — выключен, нужен админ (Admin settings → Apps & Integrations → MCP).
Дневная квота вызовов (сброс 00:00 UTC, считается ПО ВСЕМ инструментам):
| План | Вызовов/день |
|---|---|
| Free | 100 |
| Starter | 500 |
| Business | 2 000 |
| Enterprise | 10 000 |
Полный список 31 инструмента с назначением → references/mcp-tools.md.
Критичные гочи MCP
- Одна команда за раз. Авторизация строго 1:1 — ты подключён ровно к одной команде Miro, и это состояние общее для ВСЕХ MCP-клиентов сразу. Авторизовался в другую команду — предыдущая отвалилась. Доска из чужой команды → «access denied».
- Доски сами не находятся. В каждом запросе давай полный URL доски.
board_search_boardsищет только внутри авторизованной команды. - AI-кредиты жрёт ровно один инструмент —
context_get. Остальные 30 не тратят кредиты, но тратят дневную квоту. На Free одна болтливая сессия сборки доски выест все 100 вызовов. - Не ставь плагин Miro поверх этого конфига. Плагин + ручной сервер = две OAuth-сессии и дублирующиеся инструменты. Пак везёт ручной конфиг — держи что-то одно: либо этот блок в
settings.json, либо плагин. - Устаревшие имена в старых блогах:
table_create_new→table_create,draft_doc_new→doc_create,create_diagram→diagram_create,code_widget_list→code_widget_list_items. - Раскладка с первого раза редко идеальна. Говори явно, куда класть («в пустое место справа»), иначе агент положит поверх существующего. Один артефакт за запрос, не вся доска одним вызовом.
Порядок работы с layout и диаграммами
DSL-инструменты парные: сначала спецификация, потом создание.
layout_get_dsl → узнать формат → layout_create / layout_update
diagram_get_dsl → узнать формат → diagram_create
Не вызывай layout_create вслепую — формат DSL меняется, спека берётся с сервера.
Путь 2 — REST API v2
CLI: python ~/.claude/tools/miro_client.py <команда> — 31 команда, --json у каждой.
python ~/.claude/tools/miro_client.py whoami # проверить токен
python ~/.claude/tools/miro_client.py boards # список досок
python ~/.claude/tools/miro_client.py items <board_id> --type sticky_note --all
python ~/.claude/tools/miro_client.py sticky <board_id> --text "Идея" --x 0 --y 0
python ~/.claude/tools/miro_client.py connect <board_id> --from <item_id> --to <item_id>
python ~/.claude/tools/miro_client.py bulk <board_id> --file items.json
Токен — MIRO_ACCESS_TOKEN в ~/.claude/.credentials.master.env
(шаблон: ~/.claude/templates/.credentials.master.env.example).
Получение (5 минут, без Enterprise): miro.com → Settings → Your apps → Create new app →
галочку «Expire user authorization token» НЕ ставить (иначе токен живёт 60 минут) →
Permissions: boards:read + boards:write → внизу страницы «Install app and get OAuth token» → выбрать команду.
Детали эндпоинтов, лимитов и подводных камней → references/rest-api.md.
Лимиты REST
Кредитная система, 100 000 кредитов/мин на пользователя-приложение: L1 чтение = 50 кр. · L2 создание/правка = 100 кр. · L3 создание/удаление доски = 500 кр. · L4 копирование доски = 2000 кр.
POST /items/bulk тарифицируется за каждый элемент (20 штук = 2000 кредитов) — экономит задержку, но не кредиты.
Что доступно только на Enterprise
Организации и команды (/v2/orgs/*), аудит-логи, SCIM, legal hold/eDiscovery и экспорт доски через API.
На Free/Starter/Business экспорта в REST нет — выгружай из UI (PDF/картинка/CSV) либо снимай viewLink headless-браузером.
Быстрая диагностика
| Симптом | Причина и фикс |
|---|---|
| Инструментов miro не видно | Не пройдена авторизация → /mcp или claude mcp login miro |
| «Access denied» на доску | Доска в другой команде; переавторизуйся в нужную, либо дай полный URL |
| «Invalid response» при входе | Почистить куки miro.com в браузере |
| «Client not registered» | Сбросить MCP-токены и авторизоваться заново |
| Упёрлось в дневной лимит | Ждать 00:00 UTC или уйти на REST (у него своя квота) |
| Нужны стрелки/теги/группы | Это не умеет MCP — путь 2, REST |