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.

• 🧩 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 and write tracker_*, wiki_*, forms_* tools, one per SDK/CLI operation, plus a cross-cutting status tool (counts in Coverage), with honest annotations (reads are marked read-only; writes declare whether they are destructive/idempotent); ycli mcp start --read-only serves a reads-only view for cautious deployments.
• 🛡️ 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, ycli auth login, 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.

The SDK's ServiceAccountAuth (IAM tokens minted from a Yandex Cloud service-account key) needs the service-account extra: uv add 'yandex-cli[service-account]'.

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               # full read/write tool set (honest annotations)
ycli mcp start --read-only   # reads-only view for cautious deployments

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).

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

ycli sends the org id as X-Org-Id for every service (HTTP header names are case-insensitive per RFC 9110, so one casing serves all).

Optional settings follow the YCLI__<GROUP>__<SETTING> pattern; ycli rejects an invalid value at startup and names the variable:

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 — the CLI and the MCP server both write; the read scopes alone suffice only if you run the MCP server with ycli mcp start --read-only). Put the ClientID — and the Client secret if you want the headless flow — in your .env (ycli reads it from there):

YANDEX_OAUTH_CLIENT_ID=...        # from your app
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"

Coverage

ycli wraps 231 operations across 50 resources of the Tracker, Wiki, and Forms REST API — every one reachable from the Python SDK and the CLI, plus 222 MCP tools (221 domain-scoped + 1 cross-cutting: status) for agents.

Legend — operations ship on SDK + CLI, and the MCP server mirrors them with honest annotations: reads carry readOnlyHint, writes carry explicit destructive/idempotent hints, and ycli mcp start --read-only serves the reads-only view. In each table SDK and CLI mean the operation is wrapped on that surface; MCP is ✅ when the resource exposes at least one MCP tool. Resource and operation names link to the official Yandex API reference (yandex.ru/support/…/api-ref). These tables are generated from the code by scripts/gen_coverage.py — do not edit by hand.

Tracker

32 resources · 153 operations · 151 MCP tools

Issues & work items

Agile boards

Dictionaries

Fields, queues & structure

Automation & bulk

Entities, users & search

Wiki

9 resources · 43 operations · 42 MCP tools

Pages

Collaboration

Grids (dynamic tables)

Async & uploads

Identity

Forms

9 resources · 35 operations · 28 MCP tools

Surveys & questions

Responses & export

Distribution

Media

Identity

Every resource and operation above deep-links to the Yandex API reference: 227 of 231 operations resolve to their own endpoint page and 3 to their resource's page. No public API reference exists yet for tracker.linktypes, tracker.linktypes.list, shown as plain text. See CONTRIBUTING.md for the intentional exclusions (UI-only endpoints with no public REST API) and per-method notes.

Layout

src/ycli/
├── cli/                # root Typer CLI  → `ycli` / `yandex-cli` (app · context · output)
├── mcp/                # root FastMCP server → `ycli mcp start` (read/write, `[mcp]` extra)
├── settings.py         # AppConfig + Credentials (pydantic-settings)
├── log.py              # stderr logging setup (stdlib)
└── 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)
references/             # vendored Yandex API reference docs (local-only; see references/README.md)

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 and how to add an endpoint. Contributions welcome.

License

MIT © 2026 Sava Znatnov