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

cd yandex-mcp && bun install node 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's verification, its accumulated indexing and search-query history, and its sitemap and important-URL settings go with it. Adding the same site back creates a fresh host that must be verified again and starts with no history.

Nothing was sent to the Webmaster API — no host was touched.

To go ahead, call `delete