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, and --toolsets core serves a curated everyday profile when a host limits how many tools it accepts.
• 🛡️ 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.

Using an AI harness (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, opencode, Docker)? See Install in your harness.

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 --jq .summary tracker issues get TRACKER-1   # filter the JSON with jq; a string prints bare

ycli api issues/TRACKER-1 --service tracker --jq .summary           # GET (the default method)
ycli api issues/TRACKER-1/comments --service tracker -F text=@note.md   # POST: a field turns it into one
ycli api pages/descendants --service wiki -f slug=docs --paginate   # every page, as one JSON array

ycli mcp start               # full read/write tool set (honest annotations)
ycli mcp start --read-only   # reads-only view for cautious deployments

ycli mcp start --transport http --toolsets core   # needs YCLI__MCP__BASE_URL and an OAuth app

ycli mcp methods --toolsets core --read-only

{
  "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.

Check it any time with ycli auth status: it shows whose token it is (from Yandex ID), your organization (its name needs the optional directory:read_organization scope; without it you get the id and a note) and whether each service accepts the token. ycli tracker auth status (or wiki, forms) probes just that one service. Both exit non-zero when a service rejects the token.

# 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"

Exit codes

A failed ycli command exits with a code that says what kind of failure it was, so a script can branch without parsing the message.

Coverage

ycli wraps 334 operations across 62 resources of the Tracker, Wiki, and Forms REST API — every one reachable from the Python SDK and the CLI, plus 322 MCP tools (321 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

35 resources · 190 operations · 187 MCP tools

Issues & work items

Agile boards

Dictionaries

Fields, queues & structure

Automation & bulk

Entities, users & search

Wiki

11 resources · 58 operations · 56 MCP tools

Pages

Collaboration

Grids (dynamic tables)

Async & uploads

Identity

Forms

16 resources · 86 operations · 78 MCP tools

Surveys & questions

Responses & export

Integrations

Distribution

Media

Identity

Every resource and operation above deep-links to the Yandex API reference: 318 of 334 operations resolve to their own endpoint page and 15 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 `MockAPI` (no live network)

See CONTRIBUTING.md for conventions and how to add an endpoint. Contributions welcome.

License

MIT © 2026 Sava Znatnov