# kurerok-yandex-webmaster-mcp

Local-first MCP server for Yandex Webmaster. It exposes the pieces we need for
Kurerok SEO operations: search query analytics, sitemap state, indexing history,
pages in search, recrawl quota/submission, diagnostics, and link samples.

This project intentionally talks to the official Yandex Webmaster API directly.
It was informed by the public MCP ecosystem, especially:

- `altrr2/yandex-tools-mcp` for the multi-package Yandex API direction.
- `theYahia/yandex-webmaster-mcp` for a compact Webmaster-only surface.
- `yandex/yandex-search-mcp-server` for official Yandex MCP packaging ideas.

It does not require sending OAuth tokens to a hosted third party.

## Tools

Read-only:

- `yandex_get_user`
- `yandex_list_hosts`
- `yandex_get_host_summary`
- `yandex_get_diagnostics`
- `yandex_get_sitemaps`
- `yandex_get_search_queries`
- `yandex_get_indexing_history`
- `yandex_get_pages_in_search_history`
- `yandex_get_search_events_samples`
- `yandex_get_recrawl_quota`
- `yandex_get_recrawl_queue`
- `yandex_get_external_links`
- `yandex_get_broken_internal_links`

State-changing, quota-sensitive:

- `yandex_add_sitemap`
- `yandex_submit_recrawl_urls`

Both require `confirmed: true`.

## Setup

```bash
npm install
npm run build
```

Create a Yandex OAuth application with Yandex Webmaster API access and set:

```bash
export YANDEX_WEBMASTER_TOKEN="..."
export YANDEX_WEBMASTER_HOST_ID="https:kurerok.ru:443"
```

Codex/Claude MCP config:

```json
{
  "mcpServers": {
    "kurerok-yandex-webmaster": {
      "command": "node",
      "args": ["/absolute/path/to/kurerok-yandex-webmaster-mcp/dist/index.js"],
      "env": {
        "YANDEX_WEBMASTER_TOKEN": "use-env-or-secret-manager",
        "YANDEX_WEBMASTER_HOST_ID": "https:kurerok.ru:443"
      }
    }
  }
}
```

## Security Notes

- Tokens are read only from environment variables.
- The server never prints the token intentionally.
- API errors are surfaced without request headers.
- Mutating tools require explicit `confirmed: true`.
- Default auth scheme is `OAuth`, matching Yandex API examples.
- Keep the OAuth token out of shell history and MCP config files when possible.

## Kurerok Workflow

Recommended daily/weekly sequence:

1. `yandex_get_sitemaps`
2. `yandex_get_recrawl_quota`
3. `yandex_get_search_queries`
4. `yandex_get_pages_in_search_history`
5. `yandex_get_indexing_history`
6. Build a curated URL queue from sitemap + Google winners.
7. `yandex_submit_recrawl_urls` with `confirmed: true`.

Do not bulk-submit weak external-apply or low-value pages before fixing the
Yandex vacancies feed and JobPosting/directApply semantics.