yougile-api-mcp

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

Зачем

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

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

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

Related MCP server: Yougile MCP Server

Что умеет

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

Каждый инструмент помечен всеми четырьмя подсказками из спецификации 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:

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

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

{
  "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 несколько раз подряд.

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

Особенности 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.

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.