# yougile-api-mcp

MCP-сервер к API YouGile: позволяет ИИ-ассистенту (Claude Code, Claude Desktop, Cursor и любому другому MCP-клиенту) читать и вести доску YouGile — смотреть проекты и колонки, заводить и обновлять задачи, переносить их между колонками, читать и писать комментарии.

## Зачем

У YouGile нет официального MCP-сервера, а сторонние наработки маленькие и часто без файла лицензии, то есть повторно использовать их код нельзя.

API при этом обычный REST и бесплатный на любом тарифе, так что свой сервер получается короче и честнее.

Весь сервер — один файл на Node.js, без единой зависимости: скачал и запустил.

## Что умеет

Пятнадцать инструментов. Начинать всегда с `yougile_map`: он выдаёт идентификаторы, по которым работают остальные.

| Инструмент | Что делает |
| --- | --- |
| `yougile_map` | Карта доски: проекты, их доски и колонки с идентификаторами. Вызывать первым — остальные инструменты работают по этим ID. |
| `yougile_stickers` | Пользовательские стикеры (приоритеты, статусы, метки, поля) и спринты с ID состояний. Нужны, чтобы фильтровать задачи по стикеру и выставлять стикеры. |
| `yougile_create_sticker` | Создать стикер с состояниями (приоритет, статус, метка) или стикер спринтов; сразу включить его на доске. |
| `yougile_update_sticker` | Переименовать, сменить иконку или удалить стикер; добавить, переименовать, перекрасить или удалить состояния, сдвинуть даты спринта. |
| `yougile_tasks` | Список задач. Фильтры: колонка, исполнитель, подстрока заголовка, стикер и его состояние. Фильтра по проекту в API нет — фильтруйте по колонке. |
| `yougile_task` | Одна задача целиком: стикеры, чеклисты, подзадачи, учёт времени. Принимает и UUID, и код вида ABC-123. |
| `yougile_create_task` | Создать задачу в колонке: описание (HTML), исполнители, срок и дата начала, стикеры, чеклисты, подзадачи, цвет, учёт времени, таймер, секундомер. Ключ `idempotencyKey` защищает от дублей. |
| `yougile_update_task` | Изменить задачу: перенести в другую колонку, закрыть, переименовать, поменять любое поле из списка выше, снять срок или учёт времени, сменить участников чата, удалить. |
| `yougile_task_subscribers` | Кто подписан на чат задачи. |
| `yougile_comments` | Комментарии задачи (её чат), новые сверху. Фильтры: автор, текст, «начиная с», системные сообщения. |
| `yougile_comment` | Написать комментарий в задачу. Текст обычный, разметка не нужна. |
| `yougile_users` | Сотрудники компании: ID, имя, почта. Нужны, чтобы назначать задачи. |
| `yougile_me` | Сотрудник, от чьего имени выпущен ключ. |
| `yougile_create_structure` | Создать проект, доску в проекте или колонку на доске. |
| `yougile_update_structure` | Переименовать, перенести, перекрасить или удалить проект, доску или колонку; поменять состав проекта и стикеры доски. |

Каждый инструмент помечен всеми четырьмя подсказками из спецификации MCP (`annotations`: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), чтобы клиент понимал, что можно вызывать без подтверждения:

- `yougile_map`, `yougile_stickers`, `yougile_tasks`, `yougile_task`, `yougile_task_subscribers`, `yougile_comments`, `yougile_users` и `yougile_me` только читают (`readOnlyHint`);
- `yougile_create_task`, `yougile_comment`, `yougile_create_structure` и `yougile_create_sticker` добавляют новое и ничего не затирают, но при повторном вызове создадут дубль;
- `yougile_update_task`, `yougile_update_structure` и `yougile_update_sticker` могут перезаписать поля или удалить объект (`destructiveHint`).

### Чего в сервере нет и не будет

Приглашение и удаление сотрудников, роли, отделы, настройки компании, API-ключи, вебхуки и CRM-справочники сознательно не подключены. Ключ и так даёт доступ ко всей компании, а такие действия ИИ-ассистенту лучше не доверять — их удобнее делать в интерфейсе YouGile.

## Установка

Нужен Node.js версии 18 или новее — в нём есть встроенный `fetch`, на котором работает сервер. Проверить: `node --version`.

Дальше есть два пути.

**Ничего не устанавливать.** Запускать прямо из GitHub:

```
npx github:trueblackat/yougile-api-mcp
```

**Скачать репозиторий себе.** Так запуск быстрее и не зависит от сети:

```
git clone https://github.com/trueblackat/yougile-api-mcp.git
cd yougile-api-mcp
node yougile-mcp.mjs
```

Запущенный без флагов сервер ничего не печатает и ждёт команд от MCP-клиента по стандартному вводу — это нормально, так и должно быть. Остановить: Ctrl+C.

## Получить ключ

В интерфейсе YouGile кнопки «создать API-ключ» нет: ключ выпускается только через API. Поэтому в сервере есть отдельный режим `--login`.

```
node yougile-mcp.mjs --login
```

или без установки:

```
npx github:trueblackat/yougile-api-mcp --login
```

Что произойдёт:

1. Сервер напишет: `Выпуск ключа YouGile. Пароль не печатается и никуда не сохраняется.`
2. Спросит `Почта:` — введите адрес, под которым вы заходите в YouGile.
3. Спросит `Пароль:` — вводимые символы не отображаются на экране.
4. Если у аккаунта несколько компаний, покажет их нумерованным списком (`1. Название (идентификатор)`) и спросит `Номер компании:`. Если компания одна, выберет её сам.
5. Напечатает компанию и строку `Ключ, бессрочный, лимит 30 на аккаунт:`, а следующей строкой — сам ключ.

Пароль нигде не сохраняется: он живёт только в памяти процесса и уходит в YouGile, чтобы тот выдал ключ.

Ключ печатается в стандартный вывод, а все подсказки — в поток ошибок. Поэтому ключ можно сразу положить в файл, и подсказки его не испортят:

```
node yougile-mcp.mjs --login > key.txt
```

Если запускать не из терминала, а по конвейеру, сервер прочитает две строки со стандартного ввода: первая — почта, вторая — пароль.

## Проверить ключ

```
YOUGILE_API_KEY=... npx github:trueblackat/yougile-api-mcp --check
```

или, если репозиторий скачан:

```
YOUGILE_API_KEY=... node yougile-mcp.mjs --check
```

В ответ сервер напечатает строку вида `Ключ рабочий. Сотрудников видно: 2, проектов: 1`, а под ней — по строке на каждый найденный проект: `проект: Название (идентификатор)`. Список проектов в этой проверке короткий, не больше трёх — она нужна только чтобы убедиться, что ключ живой.

Если ключа нет, любая команда ответит: `Нет ключа: задайте YOUGILE_API_KEY (получить — флаг --login)`.

## Подключить

Сразу о безопасности: ключ бессрочный и наследует права сотрудника, который его выпустил, — то есть это доступ ко всей компании. Не отправляйте его в общий чат, не коммитьте в git и не вставляйте в задачи. Если ключ всё-таки утёк, выпустите новый и удалите старый через API.

### Claude Code

Одной командой, путь к файлу — абсолютный:

```
claude mcp add yougile --env YOUGILE_API_KEY=... -- node /абсолютный/путь/yougile-mcp.mjs
```

### Claude Desktop, Cursor и другие клиенты с JSON-конфигом

Добавьте в конфиг клиента блок `mcpServers`:

```json
{
  "mcpServers": {
    "yougile": {
      "command": "node",
      "args": ["/абсолютный/путь/yougile-mcp.mjs"],
      "env": {
        "YOUGILE_API_KEY": "..."
      }
    }
  }
}
```

Если репозиторий скачивать не хочется, вместо `node` и пути можно указать `npx`:

```json
{
  "mcpServers": {
    "yougile": {
      "command": "npx",
      "args": ["-y", "github:trueblackat/yougile-api-mcp"],
      "env": {
        "YOUGILE_API_KEY": "..."
      }
    }
  }
}
```

После правки конфига клиент нужно перезапустить.

## Примеры запросов

Ассистенту не нужно знать названия инструментов — достаточно сказать, что сделать. Что при этом происходит под капотом:

- **«Что у меня в работе на доске „Разработка“?»** — `yougile_map` находит доску и её колонки, `yougile_me` даёт ваш ID, `yougile_tasks` выбирает задачи по колонкам с фильтром по исполнителю.
- **«Заведи задачу „Починить экспорт в CSV“ в „Бэклог“, назначь на Олю, срок — пятница, приоритет высокий»** — `yougile_users` находит сотрудника, `yougile_stickers` — стикер приоритета и его состояние, `yougile_create_task` создаёт задачу.
- **«Перенеси ID-35 в „Готово“ и напиши в чат, что выкатили»** — `yougile_task` по коду, `yougile_update_task` с новой колонкой, `yougile_comment`.
- **«Что обсуждали в задаче ID-12 за последнюю неделю?»** — `yougile_comments` с фильтром «начиная с».
- **«Сделай стикер „Спринт“ на две недели с 1 октября и включи его на доске»** — `yougile_create_sticker` с `boardId`.
- **«Создай доску „Маркетинг“ с колонками „Идеи“, „В работе“, „Готово“»** — `yougile_create_structure` несколько раз подряд.

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

| Переменная | Обязательна | Значение |
| --- | --- | --- |
| `YOUGILE_API_KEY` | да | Ключ доступа к API. Без него сервер откажется работать. |
| `YOUGILE_BASE_URL` | нет | Адрес API. По умолчанию `https://yougile.com/api-v2`. |

## Особенности API YouGile, о которые легко споткнуться

Всё перечисленное проверено на живом аккаунте 16.09.2026.

- **API бесплатен на любом тарифе.** Цитата из официальной справки: «Использование API для любой вашей компании полностью бесплатно и не требует какого-либо тарифа или покупки дополнительных пользователей».
- **Лимит — 50 запросов в минуту на компанию.** В сервер встроен ограничитель с запасом (45 запросов) и повтор запроса, если YouGile всё-таки ответил 429.
- **Не больше 30 ключей на аккаунт.** Ключ бессрочный и наследует права выпустившего его сотрудника.
- **Описание задачи — HTML, а не markdown.** Абзацы и переносы строк размечаются тегами.
- **Срок (`deadline`) — Unix-время в миллисекундах.** Сервер принимает дату в привычном виде (`2026-09-16` или полную ISO-дату) и пересчитывает сам.
- **Удаление задачи — это `PUT` с `{deleted: true}`.** Отдельного метода DELETE у задач нет.
- **У списка задач нет фильтра по проекту.** Фильтровать можно по колонке, исполнителю и заголовку — поэтому карта проекта читается через `yougile_map`, а уже оттуда берутся идентификаторы колонок.
- **Стикеры задачи — объект `{ ID стикера: ID состояния }`.** Для стикеров-полей вместо состояния передаётся сам текст или число строкой, `"-"` открепляет стикер, `"empty"` ставит пустой.
- **Чеклисты, подзадачи и участники чата заменяются целиком.** Чтобы добавить один пункт, нужно прочитать текущий список и отправить его вместе с новым.
- **Новый стикер сам на доске не появляется** — его нужно включить в настройках доски, иначе задачам этой доски его не выставить. `yougile_create_sticker` с `boardId` делает это сам и не выключает остальные стикеры доски.
- **`GET /tasks` устарел** и отдаёт задачи в обратном порядке, поэтому сервер читает список через `GET /task-list`.
- **Задачу можно адресовать двумя способами:** по внутреннему идентификатору и по короткому коду вида `ID-35`, который виден в интерфейсе.

## Разработка

```
npm test
```

Тесты запускают сервер отдельным процессом и общаются с ним по stdio, как настоящий MCP-клиент. Вместо YouGile поднимается локальный поддельный API, поэтому ни сеть, ни ключ не нужны. Зависимостей по-прежнему нет, всё на встроенном `node:test`.

## Лицензия

MIT — свободно и без ограничений: можно пользоваться, менять, встраивать в свои продукты и распространять, в том числе коммерчески. Единственное требование — сохранить текст лицензии. Полный текст: [LICENSE](LICENSE).

## English

An MCP server for the YouGile API: lets an AI assistant (Claude Code, Claude Desktop, Cursor, any MCP client) read and manage a YouGile board — projects and columns, tasks, task updates and moves between columns, comments and company members.

Single file, no dependencies, Node.js 18+ required.

Install and run: `npx github:trueblackat/yougile-api-mcp`

YouGile has no button to create an API key in its web interface — keys are issued through the API only. Run `npx github:trueblackat/yougile-api-mcp --login`, enter your YouGile email and password (the password is never stored or printed), and the key is printed to stdout. Pass it as the `YOUGILE_API_KEY` environment variable. The key grants company-wide access, so keep it secret.

Example prompts: "What's assigned to me on the Dev board?", "Create a task 'Fix CSV export' in Backlog, assign it to Olga, due Friday, high priority", "Move ID-35 to Done and comment that it shipped", "Create a board 'Marketing' with columns Ideas, In progress, Done". Every tool declares all four MCP hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so clients can skip confirmation for reads and ask before destructive updates.

Licensed under MIT — see [LICENSE](LICENSE).