Skip to main content
Glama
README.md
# Trello MCP

MCP-сервер для Trello: доски, списки, карточки, чек-листы, комментарии, поиск.

## Установка

```
npm install && npm run build
claude mcp add --scope user trello -- node /абсолютный/путь/к/build/index.js
# или без клонирования: claude mcp add --scope user trello -- npx -y github:kholodniakruslan/trello-mcp
```

## Шаг 0. API-ключ (один раз, вручную)

Trello выдаёт ключ только владельцу аккаунта, это нельзя автоматизировать.

1. В Trello должна быть рабочая область (Workspace). Если нет: «Создать» → «Создать рабочую область».
2. https://trello.com/power-ups/admin/new → «Мое приложение не использует возможности улучшения» →
   название, рабочая область, email, автор → «Создать».
3. «Авторизация в Trello» → «Создать новый API-ключ» → «Сгенерировать API-ключ».
4. В «Одобренные ресурсы» добавьте `http://localhost:8765` (нужно только для автоматического режима).
5. Скопируйте «Ключ API» (32 символа) в `~/.config/trello-mcp/config.json`:
   ```json
   { "apiKey": "ваш_ключ" }
   ```
   или задайте переменную окружения `TRELLO_API_KEY`.

Секретный ключ (64 символа) серверу не нужен.

## Подключение аккаунта: выберите способ

Пока Trello не подключён, любой инструмент отвечает сообщением с выбором. Подключиться можно инструментом
`trello_connect`.

### Автоматически: `trello_connect {"mode":"auto"}`

Что происходит (каждый шаг приходит в виде live-лога и в итоговом ответе):

1. Проверка API-ключа.
2. Запуск локального приёмника токена на `localhost:8765`.
3. Открытие браузера со страницей согласия Trello, вам нужно нажать «Разрешить».
4. Браузер возвращает токен на локальный адрес.
5. Проверка токена запросом к Trello.
6. Токен сохраняется в `~/.config/trello-mcp/config.json` (права 600).
7. Вкладка подключения закрывается автоматически (на macOS через AppleScript: Chrome, Safari, Brave, Edge, Arc и др.; на других ОС страница пробует закрыться сама). При первом запуске macOS может спросить разрешение на управление браузером.

Если браузер не открылся, ссылка есть в логе. Ожидание подтверждения: 3 минуты.

### Вручную: `trello_connect {"mode":"manual"}`

1. Вызов без `token` вернёт инструкцию и ссылку.
2. Откройте ссылку в браузере, где вы вошли в Trello, нажмите «Разрешить».
3. Скопируйте показанный токен (~76 символов).
4. Вызовите `trello_connect {"mode":"manual","token":"<токен>"}`: сервер проверит токен и сохранит его.

### Режим по умолчанию

Чтобы не выбирать каждый раз: `TRELLO_AUTH_MODE=auto|manual` или `"authMode"` в config.json.
С `auto` сервер сам запускает подключение при первом же вызове любого инструмента.

## Язык сообщений

Сервер отвечает на том языке, на котором вы пишете, а если определить не удалось, на языке системы, иначе на английском.
Поддерживаются английский, русский и украинский (инструкции, лог подключения, страница в браузере).

Порядок выбора:
1. `TRELLO_LANG` или `"lang"` в config.json: язык закреплён принудительно, остальное игнорируется.
2. Параметр `lang`: на каждом вызове инструмента Claude передаёт код языка вашего сообщения (`ru`, `uk`, `en`…),
   сервер запоминает его на сессию. Сервер не видит ваш текст, поэтому это делает модель по инструкции сервера.
3. Язык системы: `LC_ALL`, `LC_MESSAGES`, `LANG`, затем локаль ОС.
4. Английский.

Для языка без словаря (например, `es`) сообщения идут на английском, а Claude пересказывает их на вашем языке.
Описания инструментов всегда английские: их читает модель, а не пользователь. Данные Trello не переводятся.
Добавить язык: словарь в `src/i18n.ts` (тест `npm test` проверит, что в нём есть все ключи).

## Статус и отладка

`trello_status` показывает, подключён ли сервер, настроен ли ключ, режим по умолчанию, язык сообщений и последние 30 строк лога.
Переподключение: `trello_connect` с `force: true`.

Отозвать доступ: trello.com → Аккаунт → Настройки → Приложения.

## Переменные окружения

| Переменная | Назначение |
|---|---|
| `TRELLO_API_KEY` | API-ключ (приоритетнее файла) |
| `TRELLO_TOKEN` | токен (приоритетнее файла) |
| `TRELLO_AUTH_MODE` | `auto` или `manual` |
| `TRELLO_AUTH_PORT` | порт локального приёмника (по умолчанию 8765) |
| `TRELLO_LANG` | принудительный язык сообщений: `en`, `ru`, `uk` |

## Инструменты (40)

Подключение: `trello_status`, `trello_connect`.
Доски: `list_boards`, `get_board`, `create_board`, `update_board`, `delete_board`, `copy_board`, `get_board_members`.
Списки: `get_lists`, `create_list`, `update_list` (имя, позиция, архив), `archive_list`, `copy_list`.
Карточки: `get_cards`, `get_card`, `create_card`, `update_card` (в т.ч. перенос на другую доску, даты начала и срока),
`copy_card`, `delete_card`, `set_cover`, `add_comment`, `get_comments`, `add_attachment`.
Метки: `get_labels`, `create_label`, `add_label`, `remove_label`.
Чек-листы: `create_checklist`, `add_checklist_item`, `set_checkitem_state`, `delete_checklist`.
Пользовательские поля: `get_custom_fields`, `create_custom_field` (text, number, date, checkbox, list; Power-Up включается сам),
`set_custom_field` (пустая строка очищает значение).
Участники: `get_board_members`, `invite_member`, `assign_member`, `unassign_member`, `remove_member_from_board`.
Поиск: `search` (с `limit`, `page`, `boardId`).

### Большие доски: пагинация и фильтры

`get_cards` без `limit` возвращает массив. С `limit` (и `offset`) возвращает
`{total, offset, returned, hasMore, cards}`: повторяйте вызов с `offset += limit`, пока `hasMore` истинно.
`filter` = `open` | `closed` (архив) | `all`; `compact=true` убирает описания. Читается до 1000 карточек.
`get_comments` листается через `limit` и `before` (id последнего комментария предыдущей страницы).

### Подсказки клиенту и надёжность

Чтение помечено `readOnly`, необратимые удаления (`delete_card`, `delete_board`, `delete_checklist`,
`remove_member_from_board`) помечены `destructive`. `invite_member` отправляет приглашение на email: вызывайте его
только по явной просьбе. При лимите Trello (HTTP 429) запрос повторяется до 3 раз, таймаут запроса 30 секунд.

## Установка и запуск через npx

Прямо из GitHub, без аккаунта npm (сборка выполняется при установке):

```
claude mcp add --scope user trello -- npx -y github:kholodniakruslan/trello-mcp
```

Из локальной копии: `npm install && npm run build`, затем
`claude mcp add --scope user trello -- node /абсолютный/путь/build/index.js`.

Пакет для реестра npm (`claude-trello-mcp-server`) собирается и проверяется командой `npm pack`; для публикации
(`npm publish --access public`) в аккаунте npm должна быть включена двухфакторная аутентификация.

## Самопроверка

`npm test` создаёт временные доски, прогоняет инструменты, проверяет результаты и удаляет все эти доски по их id.
Нужно подключённое состояние Trello (см. выше).

TDQS

B3.1/5.0

Scored across 40 tools

Disambiguation4/5

Most tools target a clearly distinct resource+action (get_card vs create_card vs copy_card vs delete_card, add_label vs remove_label, assign_member vs unassign_member). A few boundaries blur: archive_list overlaps with update_list's archive/unarchive, and delete_board/delete_card duplicate the close-flag behavior of update_board/update_card, though descriptions steer users to the safer option.

Naming Consistency4/5

Predominantly a verb_noun pattern (get_board, create_card, add_comment, copy_list, set_custom_field) with snake_case throughout. Minor deviations: the prefixed auth tools trello_status/trello_connect, the bare verb 'search', and inconsistent 'checkitem' vs 'checklist_item' naming.

Tool Count2/5

40 tools is heavy for an MCP surface and exceeds the threshold where an agent can hold the catalog comfortably in context. While Trello is a broad domain, several tools (auth, copy variants, separate archive/delete paths) inflate the set beyond what is strictly needed.

Completeness3/5

Core lifecycle for boards, lists, cards, labels, members, checklists, comments and custom fields is covered. However, sub-resources have add/set operations without their counterparts: no delete/update checklist item, no update/delete label, no remove attachment, no edit/delete comment, and no delete custom field — forcing dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues