yougile-api-mcp

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

Зачем

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

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

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

Related MCP server: YouTrack MCP Server

Что умеет

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

Установка

Нужен 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": "..."
      }
    }
  }
}

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

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

Особенности 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-35, который виден в интерфейсе.

Лицензия

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.

Licensed under MIT — see LICENSE.