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 © Иван Терешин