yandex-mcp
This MCP server connects Yandex advertising, analytics, search, and webmaster tools to an AI assistant, enabling both read-only analysis and gated or autonomous write workflows.
Yandex Direct: list and inspect campaigns, read supported inventory, pull campaign statistics, forecast keyword volumes by region/device, and apply allowlisted writes (add/update/delete/suspend/resume/archive/moderate, bids) idempotently; stricter human-approval flow is available via prepare/apply changes.
Yandex Metrika: list counters and goals, run bounded read-only statistics requests, build period-over-period reports with sampling metadata and exact totals, and autonomously create/update/delete goals with readback.
Yandex Wordstat: get top queries, demand dynamics over time, regional demand, and the region tree using Cloud credentials and server budget gates.
Yandex Search API (SERP): prepare asynchronous search-result jobs, submit approved queries with idempotency keys, check job status, and retrieve normalized results with provenance.
Yandex Webmaster: read user/host metadata, verification state, indexing summaries, diagnostics, query history, popular queries, indexing/search URL histories, sitemaps, external/broken links, and recrawl queues/quota/tasks; prepare and apply sitemap registrations and recrawl submissions through expiring human approvals with reconciliation.
Provides tools for submitting search jobs via the Yandex Cloud Search API and retrieving their results, along with integration for other Yandex services like Direct, Metrika, and Webmaster.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yandex-mcp Show me the traffic stats for my website in Yandex Metrika for the last week."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🇬🇧 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 |
| all | 127 | 21,986 |
| webmaster, wordstat, serp | 55 | 8,971 |
| direct | 40 | 8,055 |
| 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://playbookand guide resources, self-contained skills, structured errors withhint.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 |
| Source |
Claude Code | Supported (interactive: tools, prompts, resources; | |
VS Code (GitHub Copilot) | Supported (dynamic tool discovery); new tools may reach the agent only on the next turn | |
Gemini CLI | Supported (refreshes the tool registry) | |
Cursor | Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling | |
Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue | Unverified: no official statement found; use | — |
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=1turns 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-mcpThen 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 promptMerge 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-configThe 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-yandexCodex ~/.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 |
|
|
| Add or hide individual tools. |
| Hide every prepare/apply/write/paid-submit tool (also |
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.pyTests 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 toolsaudience_create_geo_circleCIdempotent
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_polygonCIdempotent
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_pixelCIdempotent
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_viewersCIdempotent
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_pixelBRead-onlyIdempotent
Read one pixel by filtering the documented authoritative pixel list.
Inputs: pixel_id (required). Returns: object
audience_get_segmentBRead-onlyIdempotent
Read one segment by filtering the documented authoritative segment list.
Inputs: segment_id (required). Returns: object
audience_list_pixelsARead-onlyIdempotent
List Audience tracking pixels visible to the server-side credential.
Inputs: no named parameters. Returns: object
audience_list_segmentsBRead-onlyIdempotent
List Audience segments visible to the server-side Audience credential.
Inputs: no named parameters. Returns: object
audience_manage_applyBDestructiveIdempotent
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_readBRead-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_reconcileBIdempotent
Settle an uncertain Audience management write by reading the provider; never resends.
Inputs: operation (required), idempotency_key (required), args. Returns: object
audience_reconcile_createCIdempotent
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_createBRead-onlyIdempotent
Validate a closed Audience create payload offline and return its immutable confirmation hash.
Inputs: payload (required), operation (required). Returns: object
direct_apply_changesADestructiveIdempotent
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_writeBDestructiveIdempotent
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_changesBRead-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_keywordsBRead-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_modifiersBRead-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_bidsARead-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_campaignBRead-onlyIdempotent
Get one Direct campaign by numeric id.
Inputs: campaign_id (required). Returns: object
direct_get_clientARead-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_dictionariesARead-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_statisticsARead-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_inventoryCRead-onlyIdempotent
Run a provider-native get against the explicit Direct inventory allowlist.
Inputs: params (required), service (required). Returns: object
direct_get_keyword_bidsARead-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_statisticsCRead-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_forecastCRead-onlyIdempotent
Forecast search-volume presence by device for phrases and regions.
Inputs: phrases (required), region_ids (required). Returns: object
direct_list_ad_extensionsCRead-onlyIdempotent
Callout extensions (Id, Type, Status, text). Sitelinks: direct_list_sitelinks. Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_ad_imagesBRead-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_videosCRead-onlyIdempotent
Ad video status by video Ids (required by the API). Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_agency_clientsARead-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_targetsCRead-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_businessesCRead-onlyIdempotent
Yandex Business profiles (Id, Name, IsPublished, Rubric); no Phone/Address by default. Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_campaignsCRead-onlyIdempotent
List Direct campaigns through the strict read allowlist.
Inputs: selection_criteria. Returns: object
direct_list_creativesCRead-onlyIdempotent
Creatives (image/HTML5/video/smart): Id, Type, Name, size. Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_dynamic_feed_ad_targetsCRead-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_targetsBRead-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_feedsCRead-onlyIdempotent
Product feeds: status, item count, update time. Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_leadsARead-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_setsCRead-onlyIdempotent
Shared negative keyword sets by Ids (required by the API). Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_retargeting_listsCRead-onlyIdempotent
Retargeting and audience-selection lists (Id, Type, Name, IsAvailable). Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_sitelinksCRead-onlyIdempotent
Sitelink sets (Id + Title/Href/Description). Optional Ids filter. Read-only.
Inputs: ids, limit, offset. Returns: object
direct_list_smart_ad_targetsCRead-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_strategiesARead-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_pagesCRead-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_writeBDestructiveIdempotent
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_goalBDestructiveIdempotent
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_uploadBRead-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_statisticsCRead-onlyIdempotent
Run a bounded read-only Metrika reporting request.
Inputs: params (required). Returns: object
metrika_list_countersBRead-onlyIdempotent
List Metrika counters through a server-side read-only credential.
Inputs: no named parameters. Returns: object
metrika_list_goalsCRead-onlyIdempotent
List goals for one positive Metrika counter id.
Inputs: counter_id (required). Returns: object
metrika_list_offline_conversion_uploadsCRead-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_cleanupADestructiveIdempotent
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_createAIdempotent
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_partBRead-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_evaluateARead-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_getBRead-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_listBRead-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_applyBDestructiveIdempotent
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_readBRead-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_reconcileBIdempotent
Settle an uncertain Metrika management write by reading the provider; never resends.
Inputs: operation (required), idempotency_key (required), args. Returns: object
metrika_reportARead-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_conversionsAIdempotent
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_conversionsARead-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_recrawlBIdempotent
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_sitemapCIdempotent
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_broken_links_historyBRead-onlyIdempotent
Read at most 31 days of broken internal link history.
Inputs: date_to (required), host_id (required), date_from (required). Returns: object
webmaster_get_diagnosticsBRead-onlyIdempotent
Read problems with native severity, presence state and state-change time.
Inputs: host_id (required). Returns: object
webmaster_get_external_links_historyCRead-onlyIdempotent
Read at most 31 days of external link history.
Inputs: date_to (required), host_id (required), date_from (required). Returns: object
webmaster_get_feedBRead-onlyIdempotent
One Webmaster feed's status and errors by feed URL. Read-only.
Inputs: url (required), host_id (required). Returns: object
webmaster_get_feed_problemsCRead-onlyIdempotent
Host-level feed problems in Webmaster (blocking offers). Read-only.
Inputs: host_id (required). Returns: object
webmaster_get_hostBRead-onlyIdempotent
Read metadata for an exact Webmaster host identifier.
Inputs: host_id (required). Returns: object
webmaster_get_important_url_historyBRead-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_historyBRead-onlyIdempotent
Read at most 31 days of indexing history.
Inputs: date_to (required), host_id (required), date_from (required). Returns: object
webmaster_get_ownersBRead-onlyIdempotent
Verified owners of a Webmaster host (login, verification type/date). Read-only.
Inputs: host_id (required). Returns: object
webmaster_get_pro_export_statusBRead-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_limitsARead-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_historyCRead-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_quotaBRead-onlyIdempotent
Read the daily quota and remaining submissions.
Inputs: host_id (required). Returns: object
webmaster_get_recrawl_taskBRead-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_historyCRead-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_historyCRead-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_sitemapCRead-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_historyBRead-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_summaryCRead-onlyIdempotent
Read indexing and site summary; missing metrics remain missing.
Inputs: host_id (required). Returns: object
webmaster_get_userARead-onlyIdempotent
Read the OAuth account user identifier; OAuth stays on the server.
Inputs: no named parameters. Returns: object
webmaster_get_verificationBRead-onlyIdempotent
Read ownership verification state without starting verification.
Inputs: host_id (required). Returns: object
webmaster_list_broken_linksBRead-onlyIdempotent
Read one page of broken internal link samples.
Inputs: host_id (required), limit, offset. Returns: object
webmaster_list_external_linksCRead-onlyIdempotent
Read one page of external link samples.
Inputs: host_id (required), limit, offset. Returns: object
webmaster_list_feedsBRead-onlyIdempotent
Product/service feeds added to a Webmaster host. Details via webmaster_get_feed. Read-only.
Inputs: host_id (required). Returns: object
webmaster_list_hostsBRead-onlyIdempotent
Read one bounded page of sites accessible to the server account.
Inputs: limit, offset. Returns: object
webmaster_list_important_urlsBRead-onlyIdempotent
Read one page of monitored important URLs with indexing and search status.
Inputs: host_id (required), limit, offset. Returns: object
webmaster_list_indexing_samplesBRead-onlyIdempotent
Read one page of indexing samples with continuation metadata.
Inputs: host_id (required), limit, offset. Returns: object
webmaster_list_popular_queriesBRead-onlyIdempotent
Read one page of popular queries; explicit periods are at most 31 days.
Inputs: host_id (required), limit, offset, date_to, +4 more. Returns: object
webmaster_list_pro_datesBRead-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_queueBRead-onlyIdempotent
Read one page of asynchronous recrawl requests.
Inputs: host_id (required), limit, offset. Returns: object
webmaster_list_regionsBRead-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_eventsCRead-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_urlsBRead-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_sitemapsCRead-onlyIdempotent
Read one sitemap page using the upstream sitemap identifier cursor.
Inputs: host_id (required), limit, cursor, parent_id. Returns: object
webmaster_list_user_sitemapsBRead-onlyIdempotent
Read one page of submitted sitemaps with an exclusive identifier cursor.
Inputs: host_id (required), limit, cursor. Returns: object
webmaster_manage_applyBDestructiveIdempotent
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_readBRead-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_reconcileBIdempotent
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_analyticsBRead-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_actionCIdempotent
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_exportAIdempotent
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_finishAIdempotent
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_statusARead-onlyIdempotent
Show which Yandex OAuth services have tokens (never values). Pending device-flow user_code if any. Local.
Inputs: account. Returns: object
yandex_check_updateARead-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_resultBRead-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_statusBRead-onlyIdempotent
Return durable status for an asynchronous Yandex SERP job.
Inputs: job_id (required). Returns: object
yandex_serp_submitBIdempotent
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_dynamicsBRead-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_topCRead-only
Wordstat top requests + associations; num_phrases 1..2000; devices DEVICE_* list.
Inputs: phrase (required), regions (required), devices, num_phrases. Returns: object
yandex_wordstat_regionsBRead-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_treeBRead-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
Scored across 127 tools
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.
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.
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.
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
Related MCP Connectors
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
MCP for Yandex Direct: manage ad campaigns & analytics from Claude or ChatGPT
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Related MCP Servers
- AlicenseCqualityDmaintenanceMCP server for Yandex Metrika analytics, enabling AI assistants to access traffic, content, demographics, conversion, e-commerce, and drill-down reports.312MIT
- AlicenseBqualityCmaintenanceMCP 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.10012 npm3MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.58MIT
- AlicenseAqualityBmaintenanceMCP 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.8708 npm5MIT