YouGile Secure MCP
This server provides a secure, read-first interface to the YouGile API v2 over MCP, with staged user-approved write operations for tasks.
Read-Only Tools
User: Get the profile of the API key owner (
get_current_user)Projects: List all projects or get one by UUID (
list_projects,get_project)Boards: List boards (optionally by project) or get one by UUID (
list_boards,get_board)Columns: List columns, optionally filtered by board (
list_columns)Tasks: List compact summaries with filters, get a full task by UUID, or find a task by human-readable short ID like
DEV-484(list_tasks,get_task,find_task_by_short_id)Comments: List comments on a task, oldest first (
list_task_comments)Users: List company users, optionally filtered by project or email (
list_users)Stickers: List custom stickers and their states (
list_string_stickers)All list tools support pagination (
limitcapped at 100,offset), returning ahas_moreflag
Staged Write Tools (require explicit user approval)
propose_task_create– Stage a new task (title, column, assignees, description, extra fields); returns a preview + single-use approval tokenpropose_task_update– Stage changes to an existing task (title, description, assignees, columnId, deadline, completed, archived, color, stickers, checklists, subtasks, timeTracking); returns a preview + approval tokenapply_approved_action– The only tool that mutates YouGile data; executes a staged action using its approval token after the user confirms in chat
Notable Constraints
Delete operations are not supported
Approval tokens are single-use and expire after a configurable TTL (default 10 minutes)
No login/password handling — API key only; no key leakage via error messages
UUID validation on all object IDs; HTTPS enforced for non-localhost base URLs
Supports self-hosted YouGile instances with custom base URL, SSL CA cert, and localhost HTTP opt-in
Provides read-only access to YouGile project management API, designed for use with Hermes Agent.
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 Secure MCP show me all my projects"
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 Secure MCP
A local stdio Model Context Protocol server for the YouGile API v2. Read-only by default; writes require an explicit, single-use approval issued after the user confirms the exact payload in chat.
Tools (v0.2.0)
Read-only
Tool | Purpose |
| Profile that owns the API key |
| Projects |
| Boards |
| Columns |
| Compact task summaries with server-side filters (column, assignee, title, sticker) |
| Full task object by UUID |
| Look up a task by human-readable ID such as |
| Task chat messages |
| Company users (filter by project or email) |
| Custom stickers and their states |
All list tools return {"items": [...], "has_more": bool}; limit is capped at 100, use offset for the next page.
Staged writes (explicit approval required)
Tool | Purpose |
| Stage a new task, returns a preview + single-use approval token |
| Stage changes to an existing task, same contract |
| Execute a staged action; the only tool that can mutate YouGile |
The flow is: agent stages an action → shows the preview to the user → the user approves in chat → agent calls apply_approved_action with the token. Tokens are bound to the exact payload, single-use, and expire after YOUGILE_APPROVAL_TTL_SECONDS (default 600). Delete operations are not implemented at all.
Security model
Uses only
YOUGILE_API_KEY; never accepts, stores, or sends an account login/password.Never creates, lists, or deletes YouGile API keys, webhooks, or users.
Never writes credentials to disk; API errors never include response bodies, so the key cannot leak through error messages.
All object IDs interpolated into URL paths are validated as UUIDs (no path traversal).
YOUGILE_BASE_URLmust behttps(plainhttpis allowed only for localhost).Handles the YouGile rate limit (50 requests/minute) with bounded retries on HTTP 429.
Related MCP server: yougile-mcp
Install
git clone https://github.com/ropuwz-dot/MCP-Yougile.git
cd MCP-Yougile
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]' # Linux/macOS
# .venv\Scripts\python -m pip install -e .[dev] # WindowsRun it with the API key in the environment:
export YOUGILE_API_KEY='your-api-key' # Windows: $env:YOUGILE_API_KEY='your-api-key'
.venv/bin/python run_server.py # Windows: .venv\Scripts\python run_server.pyConfiguration
Variable | Default | Purpose |
| — (required) | YouGile API v2 key |
|
| Self-hosted deployments: the |
|
| HTTP timeout |
|
| Lifetime of a staged write approval |
| — | Path to a CA bundle for self-hosted servers with a self-signed certificate |
|
| Explicit opt-in for plain-http local self-hosted servers |
Self-hosted (box) YouGile
The self-hosted Linux Server edition exposes the same API v2 on your own domain. Point YOUGILE_BASE_URL at the mainPageUrl value from your conf.json:
HTTPS with a self-signed certificate — set
YOUGILE_SSL_CA_CERTto the path of the certificate (or its CA) so TLS verification keeps working. Verification can never be turned off.Plain HTTP on a trusted local network — allowed by YouGile for local use, but here it requires
YOUGILE_ALLOW_INSECURE_HTTP=trueso the API key is never sent in clear text by accident.http://localhostworks without the flag.
Client configuration
Claude Code
claude mcp add yougile -e YOUGILE_API_KEY=your-api-key -- /absolute/path/to/MCP-Yougile/.venv/bin/python /absolute/path/to/MCP-Yougile/run_server.pyClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"yougile": {
"command": "/absolute/path/to/MCP-Yougile/.venv/bin/python",
"args": ["/absolute/path/to/MCP-Yougile/run_server.py"],
"env": { "YOUGILE_API_KEY": "your-api-key" }
}
}
}Hermes
Keep the secret in ~/.hermes/.env with 0600 permissions:
YOUGILE_API_KEY=your-api-keyThen add this server under mcp_servers in ~/.hermes/config.yaml:
mcp_servers:
yougile:
command: /absolute/path/to/MCP-Yougile/.venv/bin/python
args: [/absolute/path/to/MCP-Yougile/run_server.py]
env:
YOUGILE_API_KEY: "${YOUGILE_API_KEY}"
timeout: 60
connect_timeout: 30
sampling:
enabled: falseVerify it before restarting Hermes: hermes mcp test yougile.
Development
.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check src tests
.venv/bin/python -m mypyCI runs the same three checks on Python 3.11–3.13 for every push and pull request.
License
Available Tools
15 toolsapply_approved_actionA
Execute a previously staged write action after the user explicitly approved it in chat. Requires the single-use approval token returned by a propose_* tool.
Inputs: approval_token (required). Returns: object
find_task_by_short_idARead-onlyIdempotent
Find a task by its human-readable ID such as ID-484 (company-wide) or DEV-484 (project). Scans the task list, so it may be slow on large workspaces; prefer get_task when the UUID is known.
Inputs: short_id (required). Returns: object
get_boardBRead-onlyIdempotent
Get one board by its YouGile UUID.
Inputs: board_id (required). Returns: object
get_current_userARead-onlyIdempotent
Get the user profile that owns the configured YouGile API key.
Inputs: no named parameters. Returns: object
get_projectARead-onlyIdempotent
Get one project by its YouGile UUID.
Inputs: project_id (required). Returns: object
get_taskARead-onlyIdempotent
Get one task with all fields by its YouGile UUID.
Inputs: task_id (required). Returns: object
list_boardsARead-onlyIdempotent
List boards, optionally narrowed to a project. Returns items plus has_more; limit is capped at 100.
Inputs: limit, offset, project_id. Returns: object
list_columnsARead-onlyIdempotent
List columns, optionally narrowed to a board. Returns items plus has_more; limit is capped at 100.
Inputs: limit, offset, board_id. Returns: object
list_projectsARead-onlyIdempotent
List projects visible to the configured YouGile API key. Returns items plus has_more; limit is capped at 100, use offset to fetch the next page.
Inputs: limit, offset. Returns: object
list_string_stickersARead-onlyIdempotent
List custom stickers with their states, optionally narrowed to a board. Needed to decode task sticker values. Returns items plus has_more; limit is capped at 100.
Inputs: limit, offset, board_id. Returns: object
list_task_commentsARead-onlyIdempotent
List chat messages (comments) of a task, oldest first. Returns items plus has_more; limit is capped at 100.
Inputs: task_id (required), limit, since, offset, +1 more. Returns: object
list_tasksARead-onlyIdempotent
List tasks with server-side filters. Returns compact task summaries plus has_more (use get_task for the full object); limit is capped at 100. assigned_to accepts comma-separated user UUIDs.
Inputs: limit, title, offset, column_id, +3 more. Returns: object
list_usersARead-onlyIdempotent
List company users, optionally filtered by project or email. Returns items plus has_more; limit is capped at 100.
Inputs: email, limit, offset, project_id. Returns: object
propose_task_createARead-onlyIdempotent
Stage the creation of a task and get an approval token. Does NOT create anything: show the preview to the user, and only after the user explicitly approves call apply_approved_action with the token.
Inputs: title (required), column_id (required), assigned, description, +1 more. Returns: object
propose_task_updateARead-onlyIdempotent
Stage an update of an existing task and get an approval token. Does NOT change anything: show the preview to the user, and only after the user explicitly approves call apply_approved_action with the token. Allowed change fields: archived, assigned, checklists, color, columnId, completed, deadline, description, stickers, subtasks, timeTracking, title. Deleting tasks is not supported.
Inputs: changes (required), task_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct resource or action. Read tools (get_*, list_*) are separate from write tools (propose_*, apply_approved_action). The find_task_by_short_id is unique. No overlapping purposes.
All tool names use lower_snake_case and follow a verb_noun pattern. Verbs are consistently get_, list_, find_, propose_, apply_. No mixing of conventions.
15 tools is appropriate for a project management server. It covers listing and getting all major entities, plus a safe write pattern, without being excessive or too sparse.
Covers reading all entities and creating/updating tasks with a safe approval pattern. Missing delete for tasks and modifications for boards/columns/projects, but these are reasonable omissions given the secure nature.
Maintenance
Related MCP Connectors
Read workspaces, lists, fields, members, activity and entries, and search them in Zenkit.
Read and edit your Tasks boards: create and update tasks, comment, and track time.
Look up your agency's clients, projects, open tasks and invoices in Angelwood. Read-only.
Read users, groups, departments, courses, content and enrollments in iSpring Learn.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and developer tools to interact programmatically with Yougile workspace, supporting project, task, user, board, and column management through natural language.19MIT
- 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
- AlicenseNot gradedqualityCmaintenanceEnables read-only MCP access to Yandex Tracker for retrieving issues with comments and attachment metadata, searching issues, reading issue history, downloading attachments, and finding users. It also supports connection status checks and token configuration without exposing secrets.46 npmMIT