Skip to main content
Glama
yandex-mcp
by zai-one

🇬🇧 English · 🇷🇺 Русский

Yandex MCP

Bring Yandex advertising, analytics and search data into one conversation.

MCP server for Yandex Direct, Metrika (incl. Logs API and offline conversions), Webmaster, Wordstat, Search API and Audience: 127 tools in one server, with toolsets, read-only mode and guarded writes.

Review Direct campaigns, examine Metrika statistics, build bounded Audience segments, explore search demand and investigate Webmaster diagnostics with the same assistant. Yandex MCP connects six API groups; configure the services relevant to your work and add others as you need them.

Default: every tool (all, 127 tools, ~22k tokens per session start). To save tokens, pick platforms with YANDEX_TOOLSETS - the setup wizard (yandex-mcp-setup) or the yandex_setup prompt asks which you need and writes it for you. Measured tools/list + router cost (no Geosearch key):

Preset

Platforms

Tools

~Tokens

everything (default)

all

127

21,986

seo

webmaster, wordstat, serp

55

8,971

direct-only

direct

40

8,055

analytics

metrika, audience

30

5,786

Quick start · Connect your assistant · Issues

Try asking your assistant:

Show my Metrika counters. For the counter I choose, compare visits and goal conversions over two equal periods and highlight the largest changes.

What you can do

Your task

What the MCP server provides

Direct

Campaigns, supported inventory, portfolio strategies and statistics, including per-goal conversions and revenue; controlled changes when enabled.

Metrika

Counters, goals, filtered reports, period comparison and CSV with sampling metadata.

Search API

Asynchronous Yandex search-result jobs with saved results.

Wordstat

Top queries, demand trends, regional distribution and the region tree.

Webmaster

Indexing and site diagnostics, SQI history, important pages, search appearance/removal events, query statistics, sitemap and recrawl workflows.

Audience

Segments and pixels; guarded circle, polygon, pixel and pixel-viewer creates when explicitly enabled.

Report examples and local OAuth help explain how to compare periods, export rows and interpret partial results. API coverage notes list recently added tools with links to the Yandex documentation.

Related MCP server: yandex-marketing-mcp

Why this MCP

  • Optional lazy tool loading: set YANDEX_TOOL_LOADING=lazy (or choose it in the setup wizard) to start with a small core and enable toolsets on demand; see Lazy tool loading.

  • Six Yandex API groups in one process; enable only the toolsets you need (YANDEX_TOOLSETS, YANDEX_READ_ONLY).

  • Writes (Direct changes, Audience creates, Metrika uploads and Logs requests) are off until enabled by an env flag and use confirmation hashes or idempotency keys.

  • Agent layer: router instructions, 5 prompts (incl. yandex_setup), yandex://playbook and guide resources, self-contained skills, structured errors with hint.

  • Compared with other Yandex MCP servers on GitHub: SvechaPVL/yandex-mcp (132 tools), skiddgoddamn/yandex-marketing-mcp (153 tools) and webkoth/yandex-mcp (125 tools) still expose more total endpoints (often one tool per add/update/delete); this server matches them on documented Direct+Webmaster read methods that matter, keeps writes behind per-service gates, and ships bounded typed responses with CI on Linux and Windows.

Lazy tool loading

Optional lazy tool loading: YANDEX_TOOL_LOADING=lazy starts with a small core plus yandex_enable_toolsets and adds toolsets on demand (tools/list_changed). Startup cost (tools/list + instructions, ≈chars/4): eager ≈21872 tokens, lazy ≈2574 tokens (−88%). Default eager is unchanged; if your client ignores tools/list_changed, keep eager or reconnect after enabling. Scope: enablement is per MCP session (FastMCP session visibility), so one client's enabled toolsets never appear for another. The HTTP transport here is stateless (every request is its own session), so lazy is stdio only: an HTTP server refuses to start with it; use eager or YANDEX_TOOLSETS there.

Clients and notifications/tools/list_changed (verified against official docs, changelogs or maintainer statements, 2026-10):

Client

tools/list_changed

Source

Claude Code

Supported (interactive: tools, prompts, resources; -p/Agent SDK: tools)

docs: Dynamic tool updates

VS Code (GitHub Copilot)

Supported (dynamic tool discovery); new tools may reach the agent only on the next turn

docs, #303012

Gemini CLI

Supported (refreshes the tool registry)

PR #14375, PR #21050

Cursor

Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling

forum

Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue

Unverified: no official statement found; use eager or reconnect after enabling

—

Maintained and up to date

  • Actively maintained by ZAI.ONE: current version 0.7.0; release notes in CHANGELOG.md and Releases.

  • Built-in update check: ask the assistant to run yandex_check_update (public GitHub API, no credentials, cached; nothing is installed automatically; YANDEX_DISABLE_UPDATE_CHECK=1 turns it off).

  • Follows current MCP practice: tool annotations (read-only / destructive hints), toolsets and read-only mode, server instructions, prompts and resources, structured errors with recovery hints, secrets kept out of tool output, a token budget for tool descriptions enforced in tests, and a routing eval: messy RU/EN requests must reach the right skill, guide and tool from the short router.

  • CI runs the test suite on Linux and Windows for every pull request.

Quick start

Zero config (uv installed; no clone, no config file, no absolute paths):

claude mcp add yandex -- uvx --from "zai-yandex-mcp[standalone] @ git+https://github.com/zai-one/yandex-mcp@main" yandex-mcp

Then ask: "Подключи Яндекс Метрику". The assistant runs yandex_auth_start (OAuth device flow: open the link, enter the code), then yandex_auth_finish; the token is stored in a private file under your user profile and used immediately and after restarts. It needs your Yandex OAuth app client_id once (pass it in chat or set YANDEX_OAUTH_CLIENT_ID; OAuth guide). Without --config the server reads YANDEX_MCP_CONFIG or mcp.local.json in the per-user directory if present, and keeps state there (%APPDATA%\zai-yandex-mcp on Windows, ~/Library/Application Support/zai-yandex-mcp on macOS, ~/.config/zai-yandex-mcp elsewhere; override with YANDEX_MCP_HOME). The same uvx command works in Cursor, Codex and Claude Desktop.

Wizard (Python 3.12+ and uv installed, a Metrika OAuth token at hand):

git clone https://github.com/zai-one/yandex-mcp.git && cd yandex-mcp
uv sync --frozen --extra standalone
uv run --frozen --extra standalone python scripts/configure.py   # paste the token into the hidden prompt

Merge the generated mcp-client.json into your client (Claude Desktop, Cursor...), restart it and ask: "List my Metrika counters". Tip: add "YANDEX_TOOLSETS": "default" to the env for a smaller tool list; the assistant finds everything else through the router (yandex://guide/tool-map). Details below.

Prefer a ready package? Install the release and generate your client configuration. No source checkout is required.

Install Python 3.12–3.14 and uv. Clone with Git or download the ZIP. With a ZIP, open the extracted directory and skip the first two commands.

Each API group needs its own credentials. The wizard starts with Metrika; add Direct, Audience, Webmaster and Yandex Cloud credentials for the services you want to use. Cloud Search also needs a folder ID. Follow the service-specific setup. Audience safety and status semantics are documented in Yandex Audience.

git clone https://github.com/zai-one/yandex-mcp.git
cd yandex-mcp
uv sync --frozen --extra standalone
uv run --frozen --extra standalone python scripts/configure.py
uv run --frozen --extra standalone yandex-mcp --config mcp.local.json --check-config

The wizard creates a local configuration and stores secrets in private files. It refuses to overwrite an existing setup. --check-config validates local settings; the first request below checks your account connection.

Connect your assistant

Add this configuration to an MCP client that uses mcpServers, such as Claude Desktop or Cursor. Replace /ABSOLUTE/PATH/ with your absolute path; Windows JSON paths can use forward slashes, such as D:/Tools/.

{
  "mcpServers": {
    "yandex": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/yandex-mcp",
        "run",
        "--frozen",
        "--extra",
        "standalone",
        "yandex-mcp",
        "--config",
        "/ABSOLUTE/PATH/yandex-mcp/mcp.local.json"
      ]
    }
  }
}

The client starts the MCP server for you. Refresh its tool list, then make your first request. For clients with a different config format, reuse the same command and args; uv must be available to the client process.

First request

List my Metrika counters and the goals of the counter I select.

The default setup starts with Metrika. Once its token is accepted, the assistant can list accessible counters and read their goals. Other API groups use separately configured credentials.

If tools do not appear, check the absolute path, whether the client can find uv, and the --check-config result. For access errors, check account credentials and permissions. Installation and troubleshooting.

Other clients

# Claude Code (MCP only); --config is optional (see Zero config above)
claude mcp add yandex -- uvx --from "zai-yandex-mcp[standalone] @ git+https://github.com/zai-one/yandex-mcp@v0.7.0" yandex-mcp --config /ABSOLUTE/PATH/mcp.local.json
# Claude Code plugin (MCP + skills) from this repository; set YANDEX_MCP_CONFIG to your mcp.local.json
/plugin marketplace add zai-one/yandex-mcp
/plugin install yandex@zai-yandex

Codex ~/.codex/config.toml:

[mcp_servers.yandex]
command = "uvx"
args = ["--from", "zai-yandex-mcp[standalone] @ git+https://github.com/zai-one/yandex-mcp@v0.7.0", "yandex-mcp", "--config", "/ABSOLUTE/PATH/mcp.local.json"]
env = { YANDEX_TOOLSETS = "default" }

Cursor .cursor/mcp.json and Claude Desktop use the mcpServers block above (or "command": "uvx" with the Codex args).

Toolsets and read-only mode

Unset = every tool (127; previous behaviour). Platforms: yandex_setup_toolsets(platforms|preset, write=true) (stdio) sets only YANDEX_TOOLSETS in the active mcp.local.json (it wins over client env; restart to apply) - opt-in toolsets below are opt-in only relative to default. YANDEX_TOOLSETS=default keeps the read toolsets (direct_read, direct_reports, metrika, webmaster, wordstat, audience) plus account - about 30% fewer tool tokens. It is not strictly read-only: account includes the OAuth self-setup tools yandex_auth_start / yandex_auth_finish, which write local token files (stdio only); add YANDEX_READ_ONLY=1 (or YANDEX_DISABLED_TOOLS=yandex_auth_start,yandex_auth_finish) to hide them. The quota- and write-related metrika_logs and metrika_offline toolsets are opt-in: add them explicitly, e.g. YANDEX_TOOLSETS=default,metrika_logs. Rare reads live in opt-in direct_extra (client, dictionaries, Changes, keyword bids, bid modifiers, audience targets, retargeting lists, feeds, creatives, callouts, turbo pages, leads, videos, negative keyword sets) and webmaster_extra (owners, feeds, regions, query analytics). Administration lives in opt-in metrika_manage, webmaster_manage and audience_manage (grants, delegates, counters, filters, segments, labels, annotations, uploads, hosts, feeds, Audience segments; catalogue in yandex://guide/management), all writes through prepare -> approval -> apply. Yandex Maps organization search (maps_geosearch: maps_search_organizations, maps_search_places) is added only when YANDEX_MAPS_GEOSEARCH_API_KEY (or YANDEX_MAPS_GEOSEARCH_API_KEY_FILE, owner-private) is set - a separate Geosearch key from the developer cabinet; results are not cached and keep Yandex attribution per the Maps API terms (yandex://guide/maps-geosearch).

Variable

Effect

YANDEX_TOOLSETS

all, default or a comma list of account, direct_read, direct_extra, direct_reports, direct_write, metrika, metrika_logs, metrika_logs_write, metrika_offline, metrika_write, webmaster, webmaster_extra, webmaster_write, wordstat, search, audience, audience_write, audience_manage, metrika_manage, webmaster_manage, maps_geosearch (needs its key). Also --toolsets.

YANDEX_TOOLS / YANDEX_DISABLED_TOOLS

Add or hide individual tools.

YANDEX_READ_ONLY=1

Hide every prepare/apply/write/paid-submit tool (also --read-only).

Scopes, write flags, approvals and idempotency keys still apply to whatever is visible. The assistant can read yandex://toolsets. Errors are JSON with code, retryable, hint and docs.

Multiple accounts and agencies

Set YANDEX_ACCOUNTS_FILE to a JSON file of named profiles. Unset fields inherit the base credentials, so an agency client is just a direct_client_login; a separate account points to its own owner-private token files (paths relative to the JSON file, tokens never inline).

{
  "default": "client-a",
  "accounts": {
    "client-a": {"direct_client_login": "client-a-login", "description": "Agency client A"},
    "shop-b": {"direct_token_file": "shop-b.direct.token", "metrika_token_file": "shop-b.metrika.token"}
  }
}

Every tool then gets an optional account argument (one of the names) and yandex_list_accounts shows the profiles without secrets. Omitted account = default (or the base credentials). Without the file nothing changes: no extra argument, no extra tokens in the tool list. Use direct_list_agency_clients to find client logins.

Writes are isolated per account: idempotency keys, the write ledger and approvals belong to the account resolved for the call (Direct, Metrika, Webmaster, Audience), so a key or an approval from one account never replays or applies on another. Writes without a resolved account keep their previous ledger keys.

Direct sandbox

YANDEX_DIRECT_SANDBOX=true sends every Direct call to the official Sandbox (api-sandbox.direct.yandex.com, test data, same token; enable it once in Direct > API settings > Sandbox). Rehearse writes there first; write flags and approvals still apply. Per account: "direct_sandbox": true in YANDEX_ACCOUNTS_FILE. Sandbox writes, idempotency keys and approvals are recorded apart from production ones, so a rehearsal is never replayed or applied as a live change.

Skills, prompts and guides

Self-contained skills in skills/ (each with its own references/ and templates/): yandex-direct-audit, metrika-compare-periods, webmaster-seo-health, wordstat-demand-research, direct-safe-change. Copy a folder into ~/.claude/skills/, .agents/skills/ or .cursor/skills/, or install the plugin. MCP prompts: campaign_audit, weekly_report, seo_audit, budget_scaling; resources yandex://playbook, yandex://guide/{api-units|audit-checklist|strategies|metrics-dimensions|diagnostics-codes|wordstat-operators|prepare-apply|errors}.

Example tasks

  • "Audit my Direct campaigns for the last 30 days and list the top 5 issues."

  • "Compare organic traffic and goal reaches this week vs last week in Metrika."

  • "Check SEO health of example.com in Webmaster and give me a fix list."

  • "Collect Wordstat demand for 'купить диван' in Moscow and cluster it."

  • "Which campaigns can take 20% more budget at CPA under 900 RUB? Prepare the change, do not apply."

Access and limits

Search API jobs need a separate worker and a Cloud folder ID. Wordstat uses Cloud credentials and explicit cost limits. Write operations depend on service permissions and server policy. OAuth self-setup: yandex_auth_start / yandex_auth_finish (device-code flow, hot reload, no restart; local stdio only, never on an HTTP server; see yandex://guide/oauth) or yandex-mcp-oauth --device.

Authenticated HTTP is available for a server deployment. See HTTP setup, configuration and permissions and Python package integration.

uv sync --frozen --all-groups --extra standalone
uv run --frozen --extra standalone python scripts/verify.py
uv run --frozen --extra standalone python scripts/verify_install.py

Tests use synthetic fixtures. A passing test run does not establish live provider connectivity.

Updates

Ask your assistant to run yandex_check_update. It compares the installed version with the latest release through the public GitHub API (no credentials, no Yandex API calls or quota, 3-second timeout, result cached for 24 hours next to the state file) and returns the current and latest versions, the release notes link and the matching update command (git pull --ff-only && uv sync --frozen --extra standalone for a checkout, uv tool install --force ... for a release package). When a newer version is already known from the cache, the server mentions it once in its startup instructions. Nothing is ever installed automatically. Offline, the check reports status: unknown and the server keeps working. Set YANDEX_DISABLE_UPDATE_CHECK=1 to turn it off.

Built by ZAI.ONE

ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.

License, use and contributing

  • Use: you may install and use this MCP server freely for yourself and your organisation, including commercial work. If it helps, please consider giving the repository a ⭐ — appreciated, never required.

  • Contribute: issues and pull requests are welcome; see CONTRIBUTING.md. Never post tokens, cookies, sessions or account data.

  • Not allowed without written permission from ZAI.ONE: copying code into other projects, forking for redistribution, embedding the server in other products or offering it as a competing service.

  • License: LicenseRef-ZAI-ONE 2.0 (source-available, not open source). Third-party notices and license history: NOTICE.

Available Tools

127 tools
audience_create_geo_circleC
Idempotent

Run one guarded geo-circle create; uncertain outcomes are not resent.

Inputs: name (required), points (required), radius (required), idempotency_key (required), +4 more. Returns: object

audience_create_geo_polygonC
Idempotent

Run one guarded geo-polygon create; last is refused and unknowns are not resent.

Inputs: name (required), polygons (required), idempotency_key (required), geo_segment_type (required), +3 more. Returns: object

audience_create_pixelC
Idempotent

Run one guarded tracking-pixel create; uncertain outcomes are not resent.

Inputs: name (required), idempotency_key (required), confirmation_hash (required). Returns: object

audience_create_pixel_viewersC
Idempotent

Run one guarded pixel-viewer segment create; uncertain outcomes are not resent.

Inputs: name (required), pixel_id (required), period_length (required), times_quantity (required), +3 more. Returns: object

audience_get_pixelB
Read-onlyIdempotent

Read one pixel by filtering the documented authoritative pixel list.

Inputs: pixel_id (required). Returns: object

audience_get_segmentB
Read-onlyIdempotent

Read one segment by filtering the documented authoritative segment list.

Inputs: segment_id (required). Returns: object

audience_list_pixelsA
Read-onlyIdempotent

List Audience tracking pixels visible to the server-side credential.

Inputs: no named parameters. Returns: object

audience_list_segmentsB
Read-onlyIdempotent

List Audience segments visible to the server-side Audience credential.

Inputs: no named parameters. Returns: object

audience_manage_applyB
DestructiveIdempotent

Execute an accepted Audience write once (write flag, approval_id, idempotency_key), then read back. Same key replays the stored result. Writes.

Inputs: operation (required), approval_id (required), idempotency_key (required), args. Returns: object

audience_manage_prepareB

Open an approval for one allowlisted Audience write/upload (args: ids, query, body, csv). Bound to principal, account and exact request; nothing is sent.

Inputs: operation (required), args. Returns: object

audience_manage_readB
Read-onlyIdempotent

Documented Audience management/report reads by operation name; args = path ids, query{...}. operation='catalog' lists all operations with docs (local). Read-only.

Inputs: operation (required), args. Returns: object

audience_manage_reconcileB
Idempotent

Settle an uncertain Audience management write by reading the provider; never resends.

Inputs: operation (required), idempotency_key (required), args. Returns: object

audience_reconcile_createC
Idempotent

Reconcile one owned pending create by saved object id without sending another POST.

Inputs: payload (required), operation (required), idempotency_key (required). Returns: object

audience_validate_createB
Read-onlyIdempotent

Validate a closed Audience create payload offline and return its immutable confirmation hash.

Inputs: payload (required), operation (required). Returns: object

direct_apply_changesA
DestructiveIdempotent

Apply an accepted Direct change set (from direct_prepare_changes, approved by the operator) exactly once with approval_id + idempotency_key; re-reads campaigns to verify. Writes; spends units. Fails closed without approval.

Inputs: method (required), service (required), campaigns (required), approval_id (required), +1 more. Returns: object

direct_apply_writeB
DestructiveIdempotent

Execute an accepted Direct write once (write flag, approval_id, idempotency_key), then read back.

Same key replays the stored result. Writes; spends units.

Inputs: items (required), method (required), service (required), approval_id (required), +1 more. Returns: object

direct_check_changesB
Read-onlyIdempotent

What changed in Direct since timestamp (UTC ISO, Z) via Changes: checkCampaigns (which campaigns), check (objects in given ids), checkDictionaries. Use for incremental sync instead of re-reading everything. Read-only.

Inputs: ad_ids, method, timestamp, field_names, +2 more. Returns: object

direct_deduplicate_keywordsB
Read-onlyIdempotent

Merge duplicate phrases and add cross-negatives via KeywordsResearch.deduplicate before adding keywords. Up to 10000 phrases; nothing is saved. Read-only.

Inputs: keywords (required), operations. Returns: object

direct_get_bid_modifiersB
Read-onlyIdempotent

Bid adjustments (mobile, demographics, retargeting, regional...) by campaign/group/id; levels CAMPAIGN, AD_GROUP. Read-only.

Inputs: ids, limit, levels, offset, +2 more. Returns: object

direct_get_bidsA
Read-onlyIdempotent

Bids.get: current Bid/ContextBid plus optional search auction fields for keywords. One of campaign_ids, ad_group_ids, keyword_ids required. Monetary values are micros (×1e6). Read-only.

Inputs: limit, offset, keyword_ids, ad_group_ids, +2 more. Returns: object

direct_get_campaignB
Read-onlyIdempotent

Get one Direct campaign by numeric id.

Inputs: campaign_id (required). Returns: object

direct_get_clientA
Read-onlyIdempotent

Own Direct account info (Login, ClientId, currency, type) via Clients.get; no phones/representatives. Agencies: direct_list_agency_clients. Read-only.

Inputs: no named parameters. Returns: object

direct_get_dictionariesA
Read-onlyIdempotent

Direct reference dictionaries (Currencies, GeoRegions, TimeZones, Constants, Interests, AdCategories...). Use for region ids/min bids before forecasts or writes. GeoRegions is large. Read-only.

Inputs: names (required). Returns: object

direct_get_goal_statisticsA
Read-onlyIdempotent

Direct Reports statistics broken down by 1-10 Metrika goals and attribution models (FCCD, LC, LSCCD, AUTO). Use for CPA/ROI by goal; for plain cost/clicks use direct_get_statistics. Goal columns: . Read-only.

Inputs: goals (required), date_to (required), date_from (required), row_limit, +4 more. Returns: object

direct_get_inventoryC
Read-onlyIdempotent

Run a provider-native get against the explicit Direct inventory allowlist.

Inputs: params (required), service (required). Returns: object

direct_get_keyword_bidsA
Read-onlyIdempotent

Current keyword bids and serving status by CampaignIds, AdGroupIds or KeywordIds (one required). Change bids via direct_write service=bids. Auction data: direct_get_bids. Read-only.

Inputs: limit, offset, keyword_ids, ad_group_ids, +1 more. Returns: object

direct_get_statisticsC
Read-onlyIdempotent

Read campaign statistics; returns completed TSV rows or safe offline queue status.

Inputs: date_to (required), date_from (required), field_names, report_type, +1 more. Returns: object

direct_keyword_forecastC
Read-onlyIdempotent

Forecast search-volume presence by device for phrases and regions.

Inputs: phrases (required), region_ids (required). Returns: object

direct_list_ad_extensionsC
Read-onlyIdempotent

Callout extensions (Id, Type, Status, text). Sitelinks: direct_list_sitelinks. Read-only.

Inputs: ids, limit, offset. Returns: object

direct_list_ad_imagesB
Read-onlyIdempotent

AdImages.get: uploaded ad images (hash, name, type, subtype, associated). Optional hashes (≤10000) or associated YES/NO. Read-only.

Inputs: limit, hashes, offset, associated. Returns: object

direct_list_ad_videosC
Read-onlyIdempotent

Ad video status by video Ids (required by the API). Read-only.

Inputs: ids, limit, offset. Returns: object

direct_list_agency_clientsA
Read-onlyIdempotent

List an agency's Direct clients (Login, ClientId, ClientInfo, Currency...) via AgencyClients.get; agency tokens only. Use the Login as YANDEX_DIRECT_CLIENT_LOGIN for that client. 10 units + 1/client. Read-only.

Inputs: limit, logins, offset, archived. Returns: object

direct_list_audience_targetsC
Read-onlyIdempotent

Audience targets (retargeting/interest) by Ids, AdGroupIds or CampaignIds. Read-only.

Inputs: ids, limit, offset, ad_group_ids, +1 more. Returns: object

direct_list_businessesC
Read-onlyIdempotent

Yandex Business profiles (Id, Name, IsPublished, Rubric); no Phone/Address by default. Read-only.

Inputs: ids, limit, offset. Returns: object

direct_list_campaignsC
Read-onlyIdempotent

List Direct campaigns through the strict read allowlist.

Inputs: selection_criteria. Returns: object

direct_list_creativesC
Read-onlyIdempotent

Creatives (image/HTML5/video/smart): Id, Type, Name, size. Read-only.

Inputs: ids, limit, offset. Returns: object

direct_list_dynamic_feed_ad_targetsC
Read-onlyIdempotent

Dynamic feed ad filters (DynamicFeedAdTargets) by campaign/group/id. Read-only.

Inputs: ids, limit, offset, ad_group_ids, +1 more. Returns: object

direct_list_dynamic_text_ad_targetsB
Read-onlyIdempotent

Dynamic text ad targeting conditions by campaign/group/id. Read-only.

Inputs: ids, limit, offset, ad_group_ids, +1 more. Returns: object

direct_list_feedsC
Read-onlyIdempotent

Product feeds: status, item count, update time. Read-only.

Inputs: ids, limit, offset. Returns: object

direct_list_leadsA
Read-onlyIdempotent

Turbo page leads metadata by TurboPageIds; form data (PII) only with include_data=true. Read-only.

Inputs: limit, offset, include_data, turbo_page_ids. Returns: object

direct_list_negative_keyword_setsC
Read-onlyIdempotent

Shared negative keyword sets by Ids (required by the API). Read-only.

Inputs: ids, limit, offset. Returns: object

direct_list_retargeting_listsC
Read-onlyIdempotent

Retargeting and audience-selection lists (Id, Type, Name, IsAvailable). Read-only.

Inputs: ids, limit, offset. Returns: object

direct_list_smart_ad_targetsC
Read-onlyIdempotent

Smart-banner feed filters (SmartAdTargets) by campaign/group/id. Read-only.

Inputs: ids, limit, offset, ad_group_ids, +1 more. Returns: object

direct_list_strategiesA
Read-onlyIdempotent

List Direct shared (portfolio) strategies via Strategies.get v501 with paging. For a campaign's own strategy use direct_get_campaign; type-specific fields via direct_get_inventory service=strategies. Read-only.

Inputs: limit, offset, archived, strategy_ids. Returns: object

direct_list_turbo_pagesC
Read-onlyIdempotent

Turbo pages (Id, Name, Href); use Id for direct_list_leads. Read-only.

Inputs: ids, limit, offset. Returns: object

direct_prepare_changesA

Draft a Direct change set and open an unaccepted, expiring approval.

The draft carries a diff hash and an approval_id. A human must accept the approval before direct_apply_changes can execute it.

Inputs: changes (required). Returns: object

direct_prepare_writeB

Open an approval for one allowlisted Direct write (any service/method; yandex://guide/prepare-apply).

Bound to service, method, items, account and endpoint. Nothing is sent.

Inputs: items (required), method (required), service (required). Returns: object

direct_writeB
DestructiveIdempotent

Idempotent non-destructive Direct write (no deletes or bid changes: use direct_prepare_write) behind the server write flag and audit log. Prefer direct_prepare_changes -> direct_apply_changes for campaign changes. Writes; spends units; confirm with the user first.

Inputs: items (required), method (required), service (required), idempotency_key. Returns: object

metrika_apply_goalB
DestructiveIdempotent

Autonomously create or update a Metrika goal (idempotent, readback).

Deleting a goal needs a human approval: metrika_manage_prepare(operation='goal_delete').

Inputs: operation (required), counter_id (required), params, goal_id, +1 more. Returns: object

metrika_get_offline_conversion_uploadB
Read-onlyIdempotent

Status of one offline conversion upload (processing can take up to 3 hours). Read-only.

Inputs: counter_id (required), uploading_id (required). Returns: object

metrika_get_statisticsC
Read-onlyIdempotent

Run a bounded read-only Metrika reporting request.

Inputs: params (required). Returns: object

metrika_list_countersB
Read-onlyIdempotent

List Metrika counters through a server-side read-only credential.

Inputs: no named parameters. Returns: object

metrika_list_goalsC
Read-onlyIdempotent

List goals for one positive Metrika counter id.

Inputs: counter_id (required). Returns: object

metrika_list_offline_conversion_uploadsC
Read-onlyIdempotent

List offline conversion uploads of a counter (id, status, line counts, type). Read-only.

Inputs: counter_id (required), limit, offset, conversion_type. Returns: object

metrika_logs_cleanupA
DestructiveIdempotent

Free Logs API quota: action=clean deletes prepared files of a processed request, cancel stops an unprocessed one. Irreversible; confirm first; needs YANDEX_METRIKA_LOGS_ENABLED.

Inputs: counter_id (required), request_id (required), action, idempotency_key. Returns: object

metrika_logs_createA
Idempotent

Create a Metrika Logs API export (spends the 10 GB per-counter quota). Run metrika_logs_evaluate and confirm with the user first; needs YANDEX_METRIKA_LOGS_ENABLED. Idempotent by key; then poll metrika_logs_get.

Inputs: date1 (required), date2 (required), fields (required), source (required), +3 more. Returns: object

metrika_logs_download_partB
Read-onlyIdempotent

Preview one processed Logs API part as columns + up to max_rows (<=1000) rows; truncated=true if more. For full exports download outside chat. Read-only.

Inputs: counter_id (required), request_id (required), max_rows, part_number. Returns: object

metrika_logs_evaluateA
Read-onlyIdempotent

Check whether a Metrika Logs API export fits the counter quota (possible, max days). Use before metrika_logs_create. source=visits (ym:s:) or hits (ym:pv:); date2 before today. Read-only.

Inputs: date1 (required), date2 (required), fields (required), source (required), +1 more. Returns: object

metrika_logs_getB
Read-onlyIdempotent

Status and parts of one Logs API request; poll until status=processed, then metrika_logs_download_part. Read-only.

Inputs: counter_id (required), request_id (required). Returns: object

metrika_logs_listB
Read-onlyIdempotent

List Logs API requests of a counter with status (created, processed, canceled...) and parts. Use to find request_id. Read-only.

Inputs: counter_id (required). Returns: object

metrika_manage_applyB
DestructiveIdempotent

Execute an accepted Metrika write once (write flag, approval_id, idempotency_key), then read back. Same key replays the stored result. Writes.

Inputs: operation (required), approval_id (required), idempotency_key (required), args. Returns: object

metrika_manage_prepareA

Open an approval for one allowlisted Metrika write/upload (args: ids, query, body, csv). Bound to principal, account and exact request; nothing is sent.

Inputs: operation (required), args. Returns: object

metrika_manage_readB
Read-onlyIdempotent

Documented Metrika management/report reads by operation name; args = path ids, query{...}. operation='catalog' lists all operations with docs (local). Read-only.

Inputs: operation (required), args. Returns: object

metrika_manage_reconcileB
Idempotent

Settle an uncertain Metrika management write by reading the provider; never resends.

Inputs: operation (required), idempotency_key (required), args. Returns: object

metrika_reportA
Read-onlyIdempotent

One-call Metrika report with optional period comparison (compare_date1/2): totals, abs/% deltas, sampling info, JSON or CSV. Use for period-over-period analysis; raw params via metrika_get_statistics. <=12 metrics, 5 dimensions, 93 days. Read-only.

Inputs: date1 (required), date2 (required), metrics (required), counter_id (required), +8 more. Returns: object

metrika_upload_offline_conversionsA
Idempotent

Upload offline conversions to Metrika (affects goal stats and Direct optimisation). Needs the hash from metrika_validate_offline_conversions, user confirmation and YANDEX_METRIKA_WRITE_ENABLED.

Inputs: counter_id (required), conversions (required), idempotency_key (required), confirmation_hash (required), +2 more. Returns: object

metrika_validate_offline_conversionsA
Read-onlyIdempotent

Validate offline conversion rows locally (Target, DateTime past Unix secs, one of UserId/ClientId/Yclid/PurchaseId, Price, Currency); returns CSV preview + confirmation_hash. No API call.

Inputs: counter_id (required), conversions (required), comment, conversion_type. Returns: object

webmaster_apply_recrawlB
Idempotent

Submit one accepted URL exactly once. Uncertain POSTs are reconciled without retransmission.

Inputs: url (required), host_id (required), approval_id (required), idempotency_key (required). Returns: object

webmaster_apply_sitemapC
Idempotent

Submit one accepted sitemap with a durable key and registration readback.

Inputs: url (required), host_id (required), approval_id (required), idempotency_key (required). Returns: object

webmaster_get_diagnosticsB
Read-onlyIdempotent

Read problems with native severity, presence state and state-change time.

Inputs: host_id (required). Returns: object

webmaster_get_feedB
Read-onlyIdempotent

One Webmaster feed's status and errors by feed URL. Read-only.

Inputs: url (required), host_id (required). Returns: object

webmaster_get_feed_problemsC
Read-onlyIdempotent

Host-level feed problems in Webmaster (blocking offers). Read-only.

Inputs: host_id (required). Returns: object

webmaster_get_hostB
Read-onlyIdempotent

Read metadata for an exact Webmaster host identifier.

Inputs: host_id (required). Returns: object

webmaster_get_important_url_historyB
Read-onlyIdempotent

Read change history of one monitored URL; the URL must belong to the exact host.

Inputs: url (required), host_id (required), limit, offset. Returns: object

webmaster_get_indexing_historyB
Read-onlyIdempotent

Read at most 31 days of indexing history.

Inputs: date_to (required), host_id (required), date_from (required). Returns: object

webmaster_get_ownersB
Read-onlyIdempotent

Verified owners of a Webmaster host (login, verification type/date). Read-only.

Inputs: host_id (required). Returns: object

webmaster_get_pro_export_statusB
Read-onlyIdempotent

Status of an enhanced export task (IN_PROGRESS / SUCCESS with url / FAILED). Read-only.

Inputs: host_id (required), task_id (required). Returns: object

webmaster_get_pro_limitsA
Read-onlyIdempotent

Enhanced SERP-query export quotas for a host (GET …/pro/limits). Check before webmaster_start_pro_export. Read-only.

Inputs: host_id (required). Returns: object

webmaster_get_query_historyC
Read-onlyIdempotent

Read at most 31 days of aggregate or selected-query indicators.

Inputs: date_to (required), host_id (required), date_from (required), query_id, +2 more. Returns: object

webmaster_get_recrawl_quotaB
Read-onlyIdempotent

Read the daily quota and remaining submissions.

Inputs: host_id (required). Returns: object

webmaster_get_recrawl_taskB
Read-onlyIdempotent

Read IN_PROGRESS/DONE/FAILED; DONE does not prove search indexing.

Inputs: host_id (required), task_id (required). Returns: object

webmaster_get_search_events_historyC
Read-onlyIdempotent

Read at most 31 days of APPEARED_IN_SEARCH / REMOVED_FROM_SEARCH page counts.

Inputs: date_to (required), host_id (required), date_from (required). Returns: object

webmaster_get_search_urls_historyC
Read-onlyIdempotent

Read at most 31 days of search URL count history.

Inputs: date_to (required), host_id (required), date_from (required). Returns: object

webmaster_get_sitemapC
Read-onlyIdempotent

Read detected sitemap details or registration of a submitted sitemap.

Inputs: host_id (required), sitemap_id (required), user_added. Returns: object

webmaster_get_sqi_historyB
Read-onlyIdempotent

Read site quality index (SQI/ИКС) history; default and maximum period is 366 days.

Inputs: host_id (required), date_to, date_from. Returns: object

webmaster_get_summaryC
Read-onlyIdempotent

Read indexing and site summary; missing metrics remain missing.

Inputs: host_id (required). Returns: object

webmaster_get_userA
Read-onlyIdempotent

Read the OAuth account user identifier; OAuth stays on the server.

Inputs: no named parameters. Returns: object

webmaster_get_verificationB
Read-onlyIdempotent

Read ownership verification state without starting verification.

Inputs: host_id (required). Returns: object

webmaster_list_feedsB
Read-onlyIdempotent

Product/service feeds added to a Webmaster host. Details via webmaster_get_feed. Read-only.

Inputs: host_id (required). Returns: object

webmaster_list_hostsB
Read-onlyIdempotent

Read one bounded page of sites accessible to the server account.

Inputs: limit, offset. Returns: object

webmaster_list_important_urlsB
Read-onlyIdempotent

Read one page of monitored important URLs with indexing and search status.

Inputs: host_id (required), limit, offset. Returns: object

webmaster_list_indexing_samplesB
Read-onlyIdempotent

Read one page of indexing samples with continuation metadata.

Inputs: host_id (required), limit, offset. Returns: object

webmaster_list_pro_datesB
Read-onlyIdempotent

Dates available for enhanced SERP-query export (GET …/pro/serp/dates, up to ~550 days). Read-only.

Inputs: host_id (required). Returns: object

webmaster_list_recrawl_queueB
Read-onlyIdempotent

Read one page of asynchronous recrawl requests.

Inputs: host_id (required), limit, offset. Returns: object

webmaster_list_regionsB
Read-onlyIdempotent

Webmaster region directory (ids for webmaster_query_analytics region_ids), filter by name. Read-only.

Inputs: host_id (required), limit, filter_text. Returns: object

webmaster_list_search_eventsC
Read-onlyIdempotent

Read one page (limit 1-100) of pages that appeared in or were removed from search.

Inputs: host_id (required), limit, offset. Returns: object

webmaster_list_search_urlsB
Read-onlyIdempotent

Read one page of URLs in search; a sample is not the full index.

Inputs: host_id (required), limit, offset. Returns: object

webmaster_list_sitemapsC
Read-onlyIdempotent

Read one sitemap page using the upstream sitemap identifier cursor.

Inputs: host_id (required), limit, cursor, parent_id. Returns: object

webmaster_list_user_sitemapsB
Read-onlyIdempotent

Read one page of submitted sitemaps with an exclusive identifier cursor.

Inputs: host_id (required), limit, cursor. Returns: object

webmaster_manage_applyB
DestructiveIdempotent

Execute an accepted Webmaster write once (write flag, approval_id, idempotency_key), then read back. Same key replays the stored result. Writes.

Inputs: operation (required), approval_id (required), idempotency_key (required), args. Returns: object

webmaster_manage_prepareA

Open an approval for one allowlisted Webmaster write/upload (args: ids, query, body, csv). Bound to principal, account and exact request; nothing is sent.

Inputs: operation (required), args. Returns: object

webmaster_manage_readB
Read-onlyIdempotent

Documented Webmaster management/report reads by operation name; args = path ids, query{...}. operation='catalog' lists all operations with docs (local). Read-only.

Inputs: operation (required), args. Returns: object

webmaster_manage_reconcileB
Idempotent

Settle an uncertain Webmaster management write by reading the provider; never resends.

Inputs: operation (required), idempotency_key (required), args. Returns: object

webmaster_prepare_recrawlA

Prepare exactly one URL for human approval after ownership, quota and duplicate checks.

Inputs: url (required), host_id (required). Returns: object

webmaster_prepare_sitemapC

Prepare one sitemap registration for expiring human approval.

Inputs: url (required), host_id (required). Returns: object

webmaster_query_analyticsB
Read-onlyIdempotent

Webmaster query/URL analytics with region and text/statistic filters (up to 500 rows). Deeper than webmaster_list_popular_queries. Read-only.

Inputs: host_id (required), limit, offset, filters, +3 more. Returns: object

webmaster_reconcile_actionC
Idempotent

Read and reconcile this principal's existing action. This tool cannot send a POST.

Inputs: url (required), action (required), host_id (required), idempotency_key (required). Returns: object

webmaster_start_pro_exportA
Idempotent

Start enhanced SERP-query export (POST …/pro/serp/queries/download/). Spends daily quota; needs YANDEX_WEBMASTER_WRITE_ENABLED. use_pro_tariff=true (paid) first returns an approval to accept, then pass approval_id. Poll webmaster_get_pro_export_status.

Inputs: dates (required), host_id (required), paths, region_ids, +3 more. Returns: object

yandex_auth_finishA
Idempotent

Poll pending device-code auth; on success write 0600 token files and hot-reload (no restart). Never returns the token. Call after the user confirms in the browser.

Inputs: wait, account, max_wait_seconds. Returns: object

yandex_auth_startA

Start Yandex OAuth device-code flow: returns verification URL + user_code. Uses MCP URL elicitation when the client supports it. Pass client_id or set YANDEX_OAUTH_CLIENT_ID. No token in output.

Inputs: scope, account, services, client_id, +1 more. Returns: object

yandex_auth_statusA
Read-onlyIdempotent

Show which Yandex OAuth services have tokens (never values). Pending device-flow user_code if any. Local.

Inputs: account. Returns: object

yandex_check_updateA
Read-onlyIdempotent

Check GitHub for a newer zai-yandex-mcp release and suggest the update command. Suggest-only, 24h cache unless force=true; never calls Yandex.

Inputs: force. Returns: object

yandex_serp_get_resultB
Read-onlyIdempotent

Return raw provenance metadata and normalized Yandex SERP output.

Inputs: job_id (required). Returns: object

yandex_serp_prepareB

Prepare an asynchronous Yandex SERP request without a live provider call.

Inputs: query (required), region, response_format. Returns: object

yandex_serp_statusB
Read-onlyIdempotent

Return durable status for an asynchronous Yandex SERP job.

Inputs: job_id (required). Returns: object

yandex_serp_submitB
Idempotent

Queue an approved asynchronous Yandex SERP request.

Inputs: query (required), approval_id (required), idempotency_key (required), region, +1 more. Returns: object

yandex_setup_toolsetsA

Pick Yandex platforms (direct, metrika, webmaster, audience, wordstat, serp, maps, manage) or a preset (direct-only, analytics, seo, everything) and tool_loading eager|lazy -> YANDEX_TOOLSETS + token cost. write=true saves to mcp.local.json (stdio). No secrets.

Inputs: write, preset, platforms, tool_loading. Returns: object

yandex_wordstat_dynamicsB
Read-only

Get Wordstat demand over time using UTC dates YYYY-MM-DD and the server budget gate.

Inputs: phrase (required), from_date (required), period, devices, +2 more. Returns: object

yandex_wordstat_get_topC
Read-only

Wordstat top requests + associations; num_phrases 1..2000; devices DEVICE_* list.

Inputs: phrase (required), regions (required), devices, num_phrases. Returns: object

yandex_wordstat_regionsB
Read-only

Get Wordstat demand by region for the last 30 days through the server budget gate.

Inputs: phrase (required), region, devices. Returns: object

yandex_wordstat_regions_treeB
Read-only

Get the Wordstat region tree through Cloud credentials and the server budget gate.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 127 tools

    Disambiguation2/5

    Many tools have near-overlapping purposes: generic readers like direct_get_inventory and *_manage_read duplicate specific list/get tools, while direct_prepare_write, direct_prepare_changes, direct_write, and direct_apply_changes create multiple write paths. Rich descriptions help, but with 127 tools the boundaries remain hard to keep straight.

    Naming Consistency4/5

    Names are overwhelmingly snake_case with verb+noun patterns grouped by service (direct_*, metrika_*, webmaster_*, audience_*). Deviations such as the yandex_* prefix for Wordstat/SERP/auth/setup and occasional noun-style names (e.g., yandex_wordstat_dynamics) are minor but prevent a perfect score.

    Tool Count1/5

    127 tools is an extreme mismatch for a single MCP server; it far exceeds the 50-tool threshold and will cause context bloat and selection errors. Even accounting for the multi-platform scope, the count is unreasonable.

    Completeness4/5

    Coverage across Direct, Metrika, Webmaster, Audience, and Wordstat is extensive, with read, write, approval, and reconciliation paths. Minor gaps remain: no maps tools appear despite being referenced in setup, and destructive operations are intentionally omitted or routed through approvals.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP server for managing Yandex Direct advertising, Yandex Metrica analytics, Wordstat keyword research, and Yandex Webmaster SEO tools, with self-configuring OAuth; provides 153 tools for complete ad and search workflows from AI assistants.
      100
      12 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Yandex Direct, Metrika, Wordstat, and Webmaster APIs, providing 132 tools to manage advertising campaigns, analytics, keyword research, and reporting through any MCP-compatible client.
      58
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Yandex Metrica analytics: query web analytics metrics, goals, conversions, and raw API data using natural language from AI clients like Claude and Cursor.
      8
      708 npm
      5
      MIT