Yandex Webmaster MCP
Ask your Yandex Webmaster data in plain language — from Claude, Cursor, or any MCP client.
Read-only by design (plus URL recrawl), no secrets stored. Sign in with a
built-in public OAuth client over PKCE — no app registration, no client secret.
Early development (v0.1). The tool surface is still growing.
A Model Context Protocol server that exposes Yandex Webmaster as a small set of
flexible, well-described tools instead of one-thin-wrapper-per-endpoint. Pairs
with yandex-metrica-mcp:
run both and an agent can cross-reference search queries from Webmaster with
on-site behavior and conversions from Metrica in a single conversation.
Quickstart
1. Add the server to your MCP client (Claude Desktop, Cursor, …):
{
"mcpServers": {
"yandex-webmaster": {
"command": "npx",
"args": ["-y", "@boxlab/yandex-webmaster-mcp"]
}
}
}
2. Sign in — interactive, no secret needed:
npx @boxlab/yandex-webmaster-mcp auth
Approve access in the browser, paste the code Yandex shows you. The token is
cached at ~/.config/yandex-webmaster-mcp/token.json (mode 0600).
3. Ask your agent — e.g. "List my Webmaster hosts and show the SQI for
example.com."
Or install as a Claude Code plugin
/plugin marketplace add BoxLab-Ltd/yandex-webmaster-mcp
/plugin install yandex-webmaster-mcp@boxlab
Why
Existing community servers tend to be thin wrappers — one tool per API endpoint,
dumping raw JSON into the model's context. This server aims to be well-engineered:
fewer, smarter tools; compact, structured output; read-only by default so an
agent can explore your Webmaster data safely.
get_hosts — list the sites available to your token with their host_id,
URL and verification state; optionally a host summary (SQI, indexed/excluded
pages, site problems). Read-only. Call this first.search_queries — search-query analytics from Yandex Search: impressions,
clicks, average show/click position. report="top" ranks the queries bringing
the most traffic; report="trend" returns a time series (per query or the
site aggregate). Filter by device and date range. Read-only.get_indexing — how Yandex crawls and indexes the host. report="history"
gives crawled pages by HTTP status class over time; report="crawled" lists
example crawled URLs with their codes; report="in_search" lists example pages
currently in search. Read-only.get_diagnostics — problems detected on the site (DNS, slow response,
robots.txt, 4xx, …) with severity, active problems first. Read-only.list_sitemaps — the Sitemap files Yandex knows, with URL counts, error
counts and where each was discovered. Read-only.get_external_links — inbound links (backlinks): report="samples" for
example links with source/target, report="history" for the count over time.
Read-only.recrawl_status — remaining daily recrawl quota plus recent recrawl tasks
and their state; pass taskId to check one task. Read-only.recrawl_submit — ask Yandex to recrawl a specific URL sooner. The one
write tool; consumes one unit of the daily quota. Returns the task id.
Planned: write tools for sitemaps, original texts and feeds, deferred to a
later, opt-in release.
Requirements
Authentication
Three ways, in priority order:
- Interactive login (recommended) —
npx @boxlab/yandex-webmaster-mcp auth.
Uses the built-in public OAuth client over PKCE; the token is valid ~6 months.
- Static token — set
YANDEX_WEBMASTER_TOKEN (e.g. for CI) to an OAuth
token for an app with the webmaster:hostinfo scope.
- Your own OAuth app — set
YANDEX_OAUTH_CLIENT_ID (and
YANDEX_OAUTH_CLIENT_SECRET to enable automatic token refresh). The app needs
the webmaster:hostinfo and webmaster:verify scopes.
See .env.example for all configuration.
Development
Bun-first:
bun install
bun run dev
bun run typecheck
bun run lint
bun test
bun run build
bun run try
The published package runs on Node; local development uses Bun.
License
MIT