YouGile Secure

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
get_current_user	Profile that owns the API key
list_projects, get_project	Projects
list_boards, get_board	Boards
list_columns	Columns
list_tasks	Compact task summaries with server-side filters (column, assignee, title, sticker)
get_task	Full task object by UUID
find_task_by_short_id	Look up a task by human-readable ID such as ID-484 / DEV-484
list_task_comments	Task chat messages
list_users	Company users (filter by project or email)
list_string_stickers	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
propose_task_create	Stage a new task, returns a preview + single-use approval token
propose_task_update	Stage changes to an existing task, same contract
apply_approved_action	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_URL must be https (plain http is allowed only for localhost).
• Handles the YouGile rate limit (50 requests/minute) with bounded retries on HTTP 429.

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]  # Windows

Run 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.py

Configuration

Variable	Default	Purpose
YOUGILE_API_KEY	— (required)	YouGile API v2 key
YOUGILE_BASE_URL	https://yougile.com	Self-hosted deployments: the mainPageUrl from your conf.json
YOUGILE_TIMEOUT_SECONDS	30	HTTP timeout
YOUGILE_APPROVAL_TTL_SECONDS	600	Lifetime of a staged write approval
YOUGILE_SSL_CA_CERT	—	Path to a CA bundle for self-hosted servers with a self-signed certificate
YOUGILE_ALLOW_INSECURE_HTTP	false	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_CERT to 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=true so the API key is never sent in clear text by accident. http://localhost works 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.py

Claude 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-key

Then 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: false

Verify 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 mypy

CI runs the same three checks on Python 3.11–3.13 for every push and pull request.

License

MIT