@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" }
    }
  }
}

Related MCP server: YouTrack MCP

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)

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

Development

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

License

MIT