io.github.BoxLab-Ltd/yandex-webmaster-mcp
Query Yandex Webmaster indexing, queries, diagnostics and backlinks, and recrawl, via an AI agent.
Open source Open in the app JSON README (API)
About
Query Yandex Webmaster indexing, queries, diagnostics and backlinks, and recrawl, via an AI agent.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- boxlab-ltd
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Stars
- 3
- Open pull requests
- 2
- Last push
- 2026-08-31T21:25:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:43
- Updated
- 2026-08-29 03:01:43
- Origin id
io.github.BoxLab-Ltd/yandex-webmaster-mcp
README
# Yandex Webmaster MCP
[](https://github.com/BoxLab-Ltd/yandex-webmaster-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@boxlab/yandex-webmaster-mcp)
[](./LICENSE)
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`](https://github.com/BoxLab-Ltd/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, …):
```json
{
"mcpServers": {
"yandex-webmaster": {
"command": "npx",
"args": ["-y", "@boxlab/yandex-webmaster-mcp"]
}
}
}
```
**2. Sign in** — interactive, no secret needed:
```bash
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.
## Tools (v0.1)
- **`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
- Node.js >= 18
- A Yandex account with at least one site added in
[Yandex Webmaster](https://webmaster.yandex.ru)
## Authentication
Three ways, in priority order:
1. **Interactive login (recommended)** — `npx @boxlab/yandex-webmaster-mcp auth`.
Uses the built-in public OAuth client over PKCE; the token is valid ~6 months.
2. **Static token** — set `YANDEX_WEBMASTER_TOKEN` (e.g. for CI) to an OAuth
token for an app with the `webmaster:hostinfo` scope.
3. **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`](.env.example) for all configuration.
## Development
Bun-first:
```bash
bun install
bun run dev # watch mode
bun run typecheck
bun run lint
bun test
bun run build # emits dist/ (Node-compatible)
bun run try # smoke against the real API after `bun run auth`
```
The published package runs on Node; local development uses Bun.
## License
MIT