Content
# yougile-mcp
[](https://github.com/IvanTereshin/yougile-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/yougile-mcp)
[](./LICENSE)
[](https://nodejs.org)
A production-grade [Model Context Protocol](https://modelcontextprotocol.io) server for
[YouGile](https://yougile.com) — lets AI agents (Claude Desktop, Cursor, and any MCP client)
read and manage your YouGile projects, boards, tasks, employees and more.
> Unlike a thin API wrapper, this server ships **full CRUD coverage**, **MCP resources**
> and **ready-made prompts**, with retries, strict input validation, tests and CI.
_[Русская версия ниже ↓](#русская-версия)_
---
## Why this server
| | Typical YouGile MCP wrapper | **yougile-mcp** |
| ---------------- | --------------------------- | -------------------------------------------- |
| API coverage | partial (a few resources) | **all core resources** (projects → webhooks) |
| MCP primitives | tools only | **tools + resources + prompts** |
| Input validation | minimal | **Zod schemas on every tool** |
| Reliability | single attempt | **retry + backoff, 429/`Retry-After` aware** |
| Tests / CI | none | **unit + integration, GitHub Actions** |
| Transports | stdio | **stdio + Streamable HTTP** |
## Capabilities
**Tools (44)** — full `list` / `get` / `create` / `update` (soft-delete via `update`) for:
`projects`, `boards`, `columns`, `tasks`, `users`, `departments`, `group_chats`,
`string_stickers`, `sprint_stickers`, `webhooks` — plus task chat
(`yougile_chat_list_messages`, `yougile_chat_send_message`) and company
(`yougile_company_get`, `yougile_company_update`).
**Resources** — `yougile://projects`, `yougile://users`, and the template
`yougile://board/{boardId}` (a board with its columns).
**Prompts** — `triage_board`, `create_task_from_note`, `standup_report`, `find_stale_tasks`.
See [docs/TOOLS.md](./docs/TOOLS.md) for the full reference.
## Quick start
You need a YouGile API key: **YouGile → Settings → API**, or via
`POST https://yougile.com/api-v2/auth/keys`.
```bash
# Run directly with npx
YOUGILE_API_KEY=your-key npx yougile-mcp
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"yougile": {
"command": "npx",
"args": ["-y", "yougile-mcp"],
"env": { "YOUGILE_API_KEY": "your-key" }
}
}
}
```
### Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"yougile": {
"command": "npx",
"args": ["-y", "yougile-mcp"],
"env": { "YOUGILE_API_KEY": "your-key" }
}
}
}
```
## Configuration
All configuration is via environment variables (see [.env.example](./.env.example)):
| Variable | Required | Default | Description |
| ----------------------- | -------- | ---------------------------- | --------------------------------------- |
| `YOUGILE_API_KEY` | ✅ | — | YouGile API bearer token |
| `YOUGILE_BASE_URL` | | `https://yougile.com/api-v2` | API base URL (override for self-hosted) |
| `YOUGILE_TIMEOUT_MS` | | `30000` | Per-request timeout |
| `YOUGILE_MAX_RETRIES` | | `3` | Retries for 429/5xx/network |
| `YOUGILE_MCP_TRANSPORT` | | `stdio` | `stdio` or `http` |
| `YOUGILE_MCP_HTTP_PORT` | | `3000` | Port when `transport=http` |
### HTTP transport
```bash
YOUGILE_API_KEY=your-key YOUGILE_MCP_TRANSPORT=http YOUGILE_MCP_HTTP_PORT=3000 npx yougile-mcp
# Stateless Streamable HTTP endpoint at POST http://localhost:3000/mcp
```
## Development
```bash
npm install
npm run build # bundle to dist/ (tsup)
npm run typecheck # tsc --noEmit (strict)
npm run lint # eslint (type-checked)
npm test # vitest (unit + integration)
```
### Architecture
```
src/
config.ts # env config, Zod-validated
client/ # typed YouGile API client
http.ts # fetch + timeout + retry/backoff
yougile.ts # resource namespaces (client.tasks.list(...))
types.ts errors.ts
tools/ # MCP tools (CRUD via a shared helper) + chat/company
resources/ # MCP resources (projects, users, board template)
prompts/ # MCP prompts (triage, standup, ...)
transport/http.ts # stateless Streamable HTTP
server.ts # factory: wires client + tools/resources/prompts
index.ts # bin entrypoint (stdio | http)
```
## License
[MIT](./LICENSE) © Ivan Tereshin
---
## Русская версия
Production-grade сервер [Model Context Protocol](https://modelcontextprotocol.io) для
[YouGile](https://yougile.com). Позволяет AI-агентам (Claude Desktop, Cursor и любым
MCP-клиентам) читать и управлять проектами, досками, задачами и сотрудниками в YouGile.
> В отличие от тонкой обёртки над API, этот сервер даёт **полное покрытие CRUD**,
> **MCP-ресурсы** и **готовые prompt-сценарии**, с ретраями, строгой валидацией входных
> данных, тестами и CI.
### Возможности
**Инструменты (44)** — полный `list` / `get` / `create` / `update` (мягкое удаление через
`update`) для ресурсов: `projects`, `boards`, `columns`, `tasks`, `users`, `departments`,
`group_chats`, `string_stickers`, `sprint_stickers`, `webhooks`. Плюс чат задачи
(`yougile_chat_list_messages`, `yougile_chat_send_message`) и компания
(`yougile_company_get`, `yougile_company_update`).
**Ресурсы** — `yougile://projects`, `yougile://users` и шаблон `yougile://board/{boardId}`
(доска со своими колонками).
**Prompt-сценарии** — `triage_board` (триаж доски), `create_task_from_note` (задача из
заметки), `standup_report` (отчёт-летучка), `find_stale_tasks` (поиск «застрявших» задач).
### Быстрый старт
Нужен API-ключ YouGile: **Настройки → API** (или `POST .../api-v2/auth/keys`).
```bash
YOUGILE_API_KEY=ваш-ключ npx yougile-mcp
```
Конфигурация Claude Desktop / Cursor — см. блоки выше; все переменные окружения описаны в
[.env.example](./.env.example) и таблице [Configuration](#configuration).
### Лицензия
[MIT](./LICENSE) © Иван Терешин
