Yandex Webmaster MCP

yandex-webmaster-mcp

MCP server for Yandex Webmaster API v4. Monitor site health, indexing status, search queries, backlinks, sitemaps, and more.

Installation

This package is published as @stufently/yandex-webmaster-mcp; the unscoped name yandex-webmaster-mcp belongs to an unrelated publisher (see the note in the root README). Nothing is on the scope yet, so run it from source:

git clone https://github.com/stufently/yandex-mcp.gitcd yandex-mcp && bun installnode packages/yandex-webmaster-mcp/src/index.mjs

Configuration

Add to your MCP client config:

{  "mcpServers": {    "yandex-webmaster": {      "command": "node",      "args": ["/path/to/yandex-mcp/packages/yandex-webmaster-mcp/src/index.mjs"],      "env": {        "YANDEX_WEBMASTER_TOKEN": "your-oauth-token"      }    }  }}

Environment Variables

Authentication

To obtain an OAuth token interactively:

node packages/yandex-webmaster-mcp/src/index.mjs auth

This opens a browser for Yandex OAuth authorization and returns a token. Set the token as YANDEX_WEBMASTER_TOKEN.

Note: The Webmaster API uses Authorization: OAuth {token} (not Bearer).

Agent playbook

SKILL.md next to this file is the task-level guide for agents: the new-site flow, the regular-audit order, the recrawl rules, how the three different time-series shapes are read, and — importantly — what API v4 does not have (IndexNow, robots.txt, site region, favicon, mobile status, Metrika binding), so nothing gets invented.

Tool Reference (33 tools)

Core (3)

Statistics (2)

Diagnostics (1)

Search Queries (2)

Indexing (4)

Search Events (3)

There is no dedicated "excluded pages" resource in API v4: get-summary carries only the aggregate excluded_pages_count, and the reason a given URL was dropped lives on REMOVED_FROM_SEARCH records of /search-urls/events/samples. Since the API has no server-side event filter, count still counts events of both types and limit/offset page the mixed stream. get-search-events-samples reports what one such page contains; get-excluded-pages does the walking, so its limit counts excluded pages rather than events. Per-URL detail beyond the status code: bad_http_status for HTTP_ERROR, and target_url for the redirect target, canonical address or duplicate.

These are events in time, not a snapshot of the index. The same URL appears as REMOVED_FROM_SEARCH and later as APPEARED_IN_SEARCH — it dropped out and came back, and right now it is in search. get-excluded-pages therefore deduplicates by URL and keeps the latest event: a URL whose latest event is an appearance goes to returned_to_search, not to pages. Two consequences worth stating out loud:

• an exclusion older than the scanned window is invisible, no matter how current it is;
• deduplication spans one call. Continuing from next_offset starts with an empty state, so a page whose return fell into the previous window would be reported as excluded again — pass the previous returned_to_search in returned_urls to keep the walk honest;
• excluded_pages_count from get-summary and the length of pages are different kinds of number and are not expected to match. The tool returns the aggregate as summary_excluded_pages_count and says so in its text, instead of leaving the reader to discover a 25x gap on their own.

The per-URL status field is named excluded_url_status everywhere — in the tool descriptions, in excluded_pages from get-search-events-samples and in pages from get-excluded-pages. It is the name from the Yandex reference (ApiExcludedUrlStatus), so it can be grepped against the docs.

Links (4)

A broken-link record is a snapshot of the last time Yandex checked that link, and that moment can be months old: when source_last_access_date equals discovery_date, nothing has been re-verified since the problem was found, so the link may have been fixed long ago. Each record therefore carries days_since_last_check, never_rechecked and stale (last check older than 90 days — never_rechecked on its own does not set it), and the text block puts the warning above the list. A live check of 258 links reported broken across these sites (2026-09-02) found 10 real 404s; about 80% were 301 redirects. The API is not lying — the old one-line output just made the count read like an outage.

⚠️ In the Yandex reference the name and the description of source_last_access_date disagree: the name says source, the description says "the date the robot last visited the link's destination page". The wording here stays neutral ("last checked") because the conclusion about the record's age holds under either reading, while a conclusion about a specific page does not.

Sitemaps (4)

add-sitemap needs the host verified (404 HOST_NOT_VERIFIED otherwise). Adding a file that is already there answers 409 SITEMAP_ALREADY_ADDED; like every other non-2xx here it surfaces as an error, and its payload names the existing sitemap_id — read it as "already present" rather than retrying. Removing a sitemap (DELETE /user-added-sitemaps/{id}) exists in the API but is deliberately not wrapped here.

Important URLs (2)

Recrawl (4)

Host Management (4)

These change your Webmaster account, not just read from it.

Deleting a host

delete-host is the only irreversible tool here, and it refuses to run unless the call carries confirm: true:

{ "host_id": "https:example.com:443", "confirm": true }

Called without it, the tool returns an error result and sends nothing to the Webmaster API:

Refused: `delete-host` requires explicit confirmation.
Removing host https:example.com:443 from Yandex Webmaster is irreversible — the site'sverification, its accumulated indexing and search-query history, and its sitemap andimportant-URL settings go with it. Adding the same site back creates a fresh host that must beverified again and starts with no history.
Nothing was sent to the Webmaster API — no host was touched.
To go ahead, call `delete-host` again with host_id https:example.com:443 and `confirm: true`.To check which site this host ID stands for first, call `get-host-info` or `list-hosts`.

confirm is optional in the JSON schema on purpose: a missing confirmation has to come back as that explanation, not as a schema validation error a model cannot act on. Only a literal true counts — "true", 1 and "yes" are refused, because a guess at the protocol is not a decision to delete anything. The tool is also marked destructiveHint: true in its MCP annotations, so clients that surface tool risk can show it before the call.

The other three writes are deliberately left unguarded: add-host is additive and undone by delete-host, add-recrawl-url only queues a URL for re-crawl against a daily quota that replenishes, and add-sitemap adds a file that stays removable and takes no history with it. A confirmation on every write would train callers to pass confirm: true by reflex, which is exactly what would defeat it on the one call that matters.

Common Parameters

• host_id -- Host identifier, URL-encoded (e.g., https:example.com:443). Get it from list-hosts.
• date_from, date_to -- Dates in YYYY-MM-DD format. Strictly validated (no silent date overflow).
• limit, offset -- Pagination controls.
• device_type -- One of: ALL, DESKTOP, MOBILE, TABLET, MOBILE_AND_TABLET.

Caching

The user_id is fetched once on the first API call and cached for the session. It is automatically invalidated on 401/403 errors.

License

MIT