# 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_tasks` | Список задач. Фильтры: колонка, исполнитель, подстрока заголовка. Фильтра по проекту в API нет — фильтруйте по колонке. |
| `yougile_task` | Одна задача целиком. Принимает и UUID, и код вида ABC-123. |
| `yougile_create_task` | Создать задачу в колонке. Описание — HTML, не markdown. |
| `yougile_update_task` | Изменить задачу: перенести в другую колонку (`columnId`), закрыть (`completed`), переименовать, сменить описание, исполнителей, срок, удалить (`deleted`). |
| `yougile_comments` | Комментарии задачи (её чат), новые сверху. |
| `yougile_comment` | Написать комментарий в задачу. Текст обычный, разметка не нужна. |
| `yougile_users` | Сотрудники компании: ID, имя, почта. Нужны, чтобы назначать задачи. |

## Установка

Нужен 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_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-35`, который виден в интерфейсе.

## Лицензия

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.

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