yougile-mcp

A production-grade Model Context Protocol server for YouGile — 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 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.

# Run directly with npx
YOUGILE_API_KEY=your-key npx yougile-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "yougile": {
      "command": "npx",
      "args": ["-y", "yougile-mcp"],
      "env": { "YOUGILE_API_KEY": "your-key" }
    }
  }
}

Cursor

Add to .cursor/mcp.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):

| 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

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

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 © Ivan Tereshin

Русская версия

Production-grade сервер Model Context Protocol для YouGile. Позволяет 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).

YOUGILE_API_KEY=ваш-ключ npx yougile-mcp

Конфигурация Claude Desktop / Cursor — см. блоки выше; все переменные окружения описаны в .env.example и таблице Configuration.

Лицензия

MIT © Иван Терешин