@nebelov/yougile-mcp

MCP server for YouGile project management. 57 tools covering 100% of YouGile API v2.

Works with Claude, ChatGPT, Gemini CLI, VS Code, Cursor, and any MCP-compatible client.

README on Russian / README на русском

Quick Start

Auto-setup (recommended)

npx @nebelov/yougile-mcp --setup

Logs you into YouGile, gets an API key, and writes the config for your AI tool.

Manual setup

1. Get an API key from YouGile (Settings > API or POST /auth/keys)
2. Add to your AI tool config:

Claude Code (~/.claude.json):

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

Claude Desktop (claude_desktop_config.json):

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

Gemini CLI (~/.gemini/settings.json):

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

VS Code (.vscode/mcp.json):

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

ChatGPT Setup

Option A: Hosted (recommended)

Use the hosted server at you-mcp.com — no installation needed.

In ChatGPT (web):

1. Settings > Apps & Connectors > Advanced > Developer Mode ON
2. Click Create > paste https://you-mcp.com/mcp > Save
3. Open any chat > click + > More > Developer Mode > enable your connector
4. ChatGPT will redirect you to login with your YouGile email and password
5. Your credentials go directly to YouGile's API (zero-knowledge proxy — the server never sees your password)

Option B: Self-hosted (ngrok)

Requires ngrok (free).

Step 1. Start the server with HTTP transport:

YOUGILE_API_KEY=your-key npx @nebelov/yougile-mcp --http --port 3000

Step 2. In a second terminal, create an HTTPS tunnel:

ngrok http 3000

Copy the https://...ngrok-free.app URL from ngrok output.

Step 3. In ChatGPT (web):

1. Settings > Apps & Connectors > Advanced > Developer Mode ON
2. Click Create > paste https://YOUR-URL.ngrok-free.app/mcp > Save
3. Open any chat > click + > More > Developer Mode > enable your connector

Available Tools (57)

| Module | Tools | Description | |--------|-------|-------------| | projects | 4 | list, get, create, update | | boards | 4 | list, get, create, update | | columns | 4 | list, get, create, update | | tasks | 6 | list, get, create, update, get/set chat-subscribers | | chat | 8 | messages (list, send, get, delete) + group chats (list, get, create, update) | | users | 5 | list, get, invite, update, delete | | company | 2 | get, update | | departments | 4 | list, get, create, update | | project-roles | 5 | list, get, create, update, delete | | string-stickers | 6 | CRUD + create/update state | | sprint-stickers | 6 | CRUD + create/update state | | webhooks | 3 | list, create, update |

Bundled Skill

The package includes skill/SKILL.md — a best-practices guide for working with YouGile through AI. Copy it to your project or Claude Code skills directory for better task management.

API Patterns

• Soft delete: PUT {deleted: true} works for all entities. DELETE method only works for project roles.
• Pagination: {paging: {count, limit, offset, next}, content: [...]}. Exception: /webhooks returns raw array.
• Sticker fields: Use name (not title) for stickers and states.
• Task assigned: Array of UUIDs ["uuid1", "uuid2"], not an object.
• Chat messages: PUT only supports {deleted: true} — editing text is not possible.
• State IDs: 12-char hex strings (not UUID).

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | YOUGILE_API_KEY | Yes | YouGile API key | | YOUGILE_API_HOST_URL | No | Custom API URL (default: https://yougile.com/api-v2) |

Development

git clone https://github.com/nebelov/yougile-mcp
cd yougile-mcp
npm install
npm run dev

License

MIT