yougile-mcp
The yougile-mcp server exposes YouGile project management via Claude Code or any MCP client, enabling authentication, structural management, task operations, and team communication.
Authentication & Setup
Check auth status, store an API key directly (
yg_setup), or log in with a login/password flow to list companies and create/reuse an API key (yg_auth_companies,yg_auth_create_key). Credentials are never stored.
Project & Board Structure
List and create projects, boards, and columns (with optional color). List company employees/users (filterable by email or project, useful for resolving assignee IDs).
Task Reading & Monitoring
List tasks with powerful filters: by column, title, assignee, completion/archive status, deadline (
deadlineBeforefor overdue detection), and last-changed timestamp (changedAfterfor change detection).Fetch full details for a single task by ID.
No push/webhook support — agents must poll.
Task Writing
Create tasks in a column (title, HTML description, assignees, deadline, checklists, subtasks, color).
Update tasks: move between columns, reassign, set/clear deadlines, complete, archive, or edit title/description. Task descriptions must be HTML (not markdown).
Task Chat
Read a task's chat/comments (optionally including system messages).
Post plain-text comments to a task's chat.
Safety & Control
YG_READONLY=true: blocks all mutations.YG_CONFIRM=true: requires explicit human approval before any mutating operation executes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yougile-mcp list overdue tasks in my project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
yougile-mcp
MCP server to watch and manage YouGile tasks.
An MCP server that exposes YouGile — projects, boards, columns, tasks, and task chat — as tools an agent can call: check on overdue work, create and move tasks, and comment on task chats, all without leaving the chat.
Install
Global install:
npm i -g @skiddgoddamn/yougile-mcpRegister with Claude Code (or any MCP client that reads mcpServers JSON) — no separate install needed, npx fetches it on demand:
{
"mcpServers": {
"yougile": { "command": "npx", "args": ["-y", "@skiddgoddamn/yougile-mcp"] }
}
}The CLI binary itself is still called yougile-mcp either way.
Related MCP server: yougile-mcp
Auth
The server holds one API key per YouGile company and keeps an active company. There are two ways to get it talking to YouGile:
Bring your own key. Create an API key in the YouGile UI (Profile → API keys), then call:
yg_setup({ apiKey: "<key>" })Optionally pass
baseUrlif you're on a non-default region/host.Login/password → keys for all companies (recommended). One call fetches (or reuses) a key for every company the login can access and stores them all:
yg_auth_create_key({ login, password }) // omit companyId → all companiesPass
companyIdto fetch just one. Useyg_auth_companies({ login, password })first if you only want to preview the list without creating keys.
Using multiple companies. After the fetch-all, switch the active company with yg_company_use({ company: "<id-or-name>" }), or target one per call by passing company on any tool (e.g. yg_tasks_list({ company: "9mice" })). yg_auth_status lists every stored company with masked key previews.
Keys are stored at ~/.yougile-mcp/config.json (override the directory with YOUGILE_MCP_CONFIG_DIR). Login and password are used once per call and are never written to disk.
Tools
18 tools, all prefixed yg_.
Auth
Tool | Description |
| Show auth status: the active company and every stored company (with masked key previews). |
| Store a single YouGile API key (create one in the YouGile UI, or use |
| List YouGile companies for a login/password (no keys created). Credentials are used once and NOT stored. |
| Fetch/reuse keys from login/password and store them. Omit |
| Switch the active company for later calls (by id or name). Or pass |
Structure (projects, boards, columns, people)
Tool | Description |
| List projects. Filter by title; paginate with |
| Create a project. |
| List boards. Filter by |
| Create a board inside a project. |
| List columns. Filter by |
| Create a column on a board. |
| List company employees/users. Filter by email or |
Read (tasks & chat)
Tool | Description |
| List tasks (the workhorse for watching). Server filters: |
| Get one task by id (full card). |
| Read the chat/comments of a task ( |
Write (tasks & chat)
Tool | Description |
| Create a task in a column. |
| Update a task: move ( |
| Post a comment to a task's chat. |
Task descriptions are HTML
The description field on yg_task_create / yg_task_update is rendered as HTML — not markdown, not plain text. This is the single easiest thing to get wrong: newlines are ignored, so a plain-text description with \n collapses into one unreadable wall of text in the UI, and the API happily accepts it without complaint.
Use <p> paragraphs, <b> / <i>, <ul>/<ol> + <li>, <br>, <a href>:
yg_task_update({
id: "…",
description: "<p><b>Goal.</b> Ship it.</p><ul><li>step one</li><li>step two</li></ul>",
})Reading a task back returns the same HTML, so round-tripping a description is safe.
Chat messages are not HTML. yg_task_comment takes plain text — newlines there work as expected. Don't send HTML to it.
Watching (on-demand)
This server has no push/webhook mechanism — YouGile is watched on-demand, by having an agent call the list tools on a schedule and reason about the results. Two patterns:
1. Overdue-task sweep. A routine (e.g. Claude Code's /schedule or /loop) that runs every 30 minutes:
now = <current time, ms epoch>
for each board you care about:
columns = yg_columns_list({ boardId })
for each column:
overdue = yg_tasks_list({
columnId: column.id,
deadlineBefore: now,
completed: false,
archived: false,
})
if overdue.count > 0: report them (e.g. post a summary message)2. Change delta since last run. The agent tracks the timestamp of its previous run (e.g. in its own scratch state) and only asks for what changed since then:
lastRunMs = <timestamp saved from previous run>
changed = yg_tasks_list({ columnId, changedAfter: lastRunMs })
// report `changed.content`, then persist `now` as the new lastRunMs for next timeBoth patterns compose: run the delta sweep on every tick, and the full overdue sweep less often (e.g. once a day) as a safety net against missed deltas.
Env vars
Var | Meaning | Default |
| Directory where |
|
| YouGile API base URL (for self-hosted/regional instances). |
|
| Fallback API key used if none is stored yet in | (unset) |
|
|
|
|
|
|
| Log verbosity: |
|
|
|
|
| If set, also appends log lines to this file (in addition to stderr). | (unset — stderr only) |
Safety
YG_READONLY=true— watch-only mode. Every tool whose name contains_create,_update, or_comment(i.e. everything that mutates YouGile) is denied before it runs. Auth tools (yg_setup,yg_auth_create_key, etc.) are exempt, since configuring the server isn't a YouGile-data mutation. Use this when you want an agent to report on tasks but never touch them.YG_CONFIRM=true— confirmation mode. Mutating tools return aconfirm_requiredpayload describing the call instead of executing it; re-issue the same call withconfirm: trueto actually run it. Useful for human-in-the-loop review before an agent creates/updates/comments.Both can be combined with normal MCP client behavior (READONLY wins — a blocked call never reaches the CONFIRM check).
Security note (important): YG_LOG_BODIES=true logs raw request/response bodies to stderr and/or YG_LOG_FILE. This includes login and password on yg_auth_companies/yg_auth_create_key calls, and the full API key in yg_auth_create_key's response. Leave it off (the default) except for local debugging on your own machine, and never enable it anywhere logs are shared, aggregated, or shipped off-box.
Dev
npm install
npm test
npm run buildCaveats
Some YouGile GET query-param and task-field shapes are still being finalized against the live API. In particular,
coloris typed as an integer (1–16) onyg_column_createbut as a free-form string onyg_task_create— this matches the current live API behavior observed during development but may need reconciling if YouGile's docs/behavior change.List tools (
yg_projects_list,yg_boards_list,yg_columns_list,yg_employees_list,yg_tasks_list,yg_task_chat_get) takelimit/offsetfor pagination — YouGile caps pages at roughly 50 items, so boards/projects with more items than that need multiple paged calls to see everything.
Available Tools
17 toolsyg_auth_companiesB
List YouGile companies for a login/password so you can pick a companyId. Credentials are used once and NOT stored.
Inputs: login (required), password (required).
yg_auth_create_keyC
Create (or reuse) a YouGile API key for a company from login/password, and store it. Credentials are used once and NOT stored.
Inputs: login (required), password (required), companyId (required), companyName.
yg_auth_statusA
Show YouGile auth status: whether an API key is stored and which company (if known).
Inputs: no named parameters.
yg_board_createC
Create a board inside a project.
Inputs: title (required), projectId (required).
yg_boards_listB
List boards. Filter by projectId/title.
Inputs: limit, title, offset, projectId, +1 more.
yg_column_createC
Create a column on a board.
Inputs: title (required), boardId (required), color.
yg_columns_listB
List columns. Filter by boardId/title.
Inputs: limit, title, offset, boardId, +1 more.
yg_employees_listA
List company employees/users. Filter by email or projectId. Use to resolve assignee ids.
Inputs: email, limit, offset, projectId.
yg_project_createC
Create a project.
Inputs: title (required), users.
yg_projects_listB
List projects. Filter by title; paginate with limit/offset.
Inputs: limit, title, offset, includeDeleted.
yg_setupA
Store a YouGile API key (create one in the YouGile UI, or use yg_auth_create_key). Optionally set a custom base URL for self-hosted instances.
Inputs: apiKey (required), baseUrl.
yg_task_chat_getB
Read the chat/comments of a task (chatId = task id). Useful for watching discussion.
Inputs: taskId (required), limit, offset, includeSystem.
yg_task_commentC
Post a comment to a task's chat.
Inputs: text (required), taskId (required), label.
yg_task_createC
Create a task in a column.
Inputs: title (required), columnId (required), color, archived, +6 more.
yg_task_getA
Get one task by id (full card).
Inputs: id (required).
yg_tasks_listA
List tasks (the workhorse for watching). Server filters: columnId, title, includeDeleted, limit, offset. Client filters applied to the page: assignedTo (user id), completed, archived, deadlineBefore (ms epoch or ISO), changedAfter (ms epoch or ISO, vs task timestamp).
Inputs: limit, title, offset, archived, +6 more.
yg_task_updateA
Update a task: move (columnId), assign, deadline, complete, archive, edit title/description. Only provided fields change. Pass deadline=null to clear.
Inputs: id (required), title, archived, assigned, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool maps to a distinct resource-action pair: auth setup, companies, projects, boards, columns, employees, tasks, and task chat. There is no meaningful overlap even within the auth cluster because each tool handles a different step or data source.
The yg_ prefix and the general resource_action pattern are consistently used, and plural list verbs are separated from singular create/get/update verbs. Minor deviations such as yg_setup, yg_auth_status, and yg_auth_companies (which lacks an explicit verb) keep it from being a perfect 5.
Seventeen tools is reasonable for a project management MCP server, covering authentication, projects, boards, columns, employees, tasks, and comments. The count feels intentional rather than bloated, and every tool has a clear role in the workflow.
The task lifecycle is well covered with list/get/create/update plus chat and comments, and project/board/column creation supports the hierarchy. Missing update/delete operations for projects, boards, and columns are minor gaps for a tool set primarily aimed at task monitoring and management.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Kanban board for teams and coding agents: manage tasks, subtasks, sprints and wiki pages via MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceIntegrates with YouGile to allow AI assistants to create, update, and manage projects, tasks, and team members via the MCP protocol.13-
- AlicenseBqualityDmaintenanceA production-grade Model Context Protocol server for YouGile that lets AI agents read and manage projects, boards, tasks, employees, and more.4416 npm2MIT
- AlicenseAqualityCmaintenanceMCP server for YouGile project management. Provides 57 tools covering 100% of YouGile API v2, enabling natural language management of projects, boards, columns, tasks, chats, users, and more.5774 npm10MIT
- AlicenseNot gradedqualityCmaintenanceAn unofficial, security-focused MCP server for YouGile REST API, providing policy-controlled tools with read-only defaults and optional direct-write profiles.4MIT