ycli

One Yandex 360 toolkit — four ways to use it. Drive Tracker, Wiki, and Forms from a CLI, an MCP server, a Python SDK, or a Claude Code plugin. Built for AI agents first — pleasant for humans too.

Why ycli

• 🧩 One SDK, four surfaces — write logic once, use it as a CLI, an MCP server, a Python library, or a Claude Code plugin.
• 🤖 Agent-native — the MCP server exposes read-only tracker_*, wiki_*, forms_* tools so agents explore safely; writes stay in the CLI/SDK.
• 🛡️ Trustworthy — typed pydantic models, the real Yandex API quirks handled for you, and a test suite kept at 100% coverage.
• ⚡ Zero-friction start — uv add yandex-cli, two env vars, go.

Install

uv add yandex-cli            # CLI + Python SDK
uv add 'yandex-cli[mcp]'     # …plus the MCP server (`ycli mcp start`)

Run it without installing, or install it as a standalone tool:

uvx yandex-cli --help                 # one-off, no install
uv tool install yandex-cli            # persistent CLI
uv tool install 'yandex-cli[mcp]'     # …with the MCP server

pip install yandex-cli works too. The CLI ships as both yandex-cli and the short ycli.

Quick start

Pick the surface that fits how you work.

uv add yandex-cli
ycli --help
ycli tracker issues get TRACKER-1
ycli wiki pages get onboarding

ycli tracker issues get TRACKER-1            # auto: a pretty table on a TTY…
ycli tracker issues get TRACKER-1 | jq .     # …and raw JSON when piped (agent/script-safe)
ycli -o yaml wiki pages get onboarding       # or: -o json | -o yaml | -o pretty

ycli mcp start

ycli mcp methods

{
  "mcpServers": {
    "yandex": {
      "command": "uvx",
      "args": ["--from", "yandex-cli[mcp]", "ycli", "mcp", "start"],
      "env": {
        "YANDEX_ID_OAUTH_TOKEN": "...",
        "YANDEX_ID_ORGANIZATION_ID": "..."
      }
    }
  }
}

from ycli.yandex.tracker.client import TrackerClient

tracker = TrackerClient(oauth_token="…", organization_id="…")
issue = tracker.issues.get("TRACKER-1")
print(issue.summary)

/plugin marketplace add bim-ba/ycli
/plugin install yandex-360@ycli

Skills (Claude Code plugin)

The skills encode the read/write commands and the gnarly Yandex API quirks (epic-vs-parent, transition discovery, permanent wiki slugs, fields= rules, Forms host/header traps, answers pagination).

Coverage

ycli wraps the near-complete public REST API of Tracker, Wiki, and Forms — 230 operations across 50 resources, every one reachable from the Python SDK and the CLI. Reads are additionally exposed as 80 read-only MCP tools for agents.

Legend — reads ship on SDK + CLI + MCP; writes and binary downloads on SDK + CLI (the MCP server is read-only by design). In each table SDK and CLI mean the operation is wrapped on that surface; MCP is ✅ when the resource exposes at least one read-only tool. These tables are generated from the code by scripts/gen_coverage.py — do not edit by hand.

Tracker

32 resources · 153 operations · 57 MCP tools

Issues & work items

Agile boards

Dictionaries

Fields, queues & structure

Automation & bulk

Entities, users & search

Wiki

9 resources · 43 operations · 13 MCP tools

Pages

Collaboration

Grids (dynamic tables)

Async & uploads

Identity

Forms

9 resources · 34 operations · 10 MCP tools

Surveys & questions

Responses & export

Distribution

Media

Identity

See docs/api-coverage.md for the intentional exclusions (UI-only endpoints with no public REST API) and per-method notes.

Configure

ycli reads two values from the environment (or a .env file — cp .env.example .env):

YANDEX_ID_OAUTH_TOKEN=...        # a Yandex OAuth token with Tracker/Wiki/Forms access
YANDEX_ID_ORGANIZATION_ID=...    # your Yandex 360 organization id

Header casing differs per service (Tracker X-Org-ID, Wiki/Forms X-Org-Id) — ycli handles it for you.

Get your credentials

Yandex issues OAuth tokens only through a registered application, so it's a one-time app registration plus one command.

1. Register an OAuth app at oauth.yandex.ru and grant it the Tracker, Wiki, and Forms permissions (read and write for the full CLI; the read scopes alone are enough for the read-only MCP server). Copy the ClientID — and the Client secret if you want the headless flow:

export YANDEX_OAUTH_CLIENT_ID=...        # from your app
export YANDEX_OAUTH_CLIENT_SECRET=...    # optional — enables the headless device flow

2. Log in. ycli auth login gets a token, detects your organization, and writes both into .env:

ycli auth login

• client id + secret → the device flow: ycli prints a code and a https://ya.ru/device link; approve there and it captures the token — no redirect, works over SSH.
• only the client id (or --implicit) → the browser flow: ycli opens the Yandex authorize page; approve, then copy the token it displays and paste it back.

# 1. start the flow — returns a user_code + verification_url
curl -s -X POST https://oauth.yandex.ru/device/code -d "client_id=$YANDEX_OAUTH_CLIENT_ID"
# 2. open https://ya.ru/device, enter the user_code, approve
# 3. exchange the device_code for the token
curl -s -X POST https://oauth.yandex.ru/token \
  -d grant_type=device_code -d "code=<device_code>" \
  -d "client_id=$YANDEX_OAUTH_CLIENT_ID" -d "client_secret=$YANDEX_OAUTH_CLIENT_SECRET"

Project layout

src/ycli/
├── cli.py              # root Typer CLI  → `ycli` / `yandex-cli`
├── mcp.py              # root FastMCP server → `ycli mcp start` (read-only, `[mcp]` extra)
├── log.py              # central loguru config
└── yandex/
    ├── tracker/        # per-domain SDK …
    ├── wiki/           #   each resource group has:
    └── forms/          #   client.py · cli.py · mcp.py · models.py
plugins/yandex-360/     # distributable Claude Code plugin (skills + instructions)
docs/references/        # vendored Yandex API reference docs

Development

uv sync --all-extras   # --all-extras pulls in the `mcp` extra the tests exercise
uv run pytest          # 100% coverage gate; HTTP stubbed with `responses` (no live network)

See CONTRIBUTING.md for conventions. Contributions welcome — the coverage roadmap is a good place to find a first issue.

License

MIT © 2026 Sava Znatnov