Google search analytics cannot explain everything happening to a site in Yandex. Webmaster has its own reports about pages in search, diagnostics, queries, and recrawl requests. I built a separate Go MCP server to make those reports available in the same agent conversation without losing track of their origin.
Webmaster MCP is an independent open-source project, not an official Yandex product. It uses the Yandex Webmaster API with one OAuth token per installation. Clients connect through Streamable HTTP and call tools with defined inputs and result schemas.
Start with the exact host identifier
The first useful call is list_hosts. Pass the returned host_id exactly. https:example.com:443 and http:example.com:80 identify different hosts. Constructing an identifier from a domain name can select the wrong variant or produce an access error.
get_summary provides SQI, page counts, and a problem summary. get_diagnostics exposes individual check states. get_popular_queries and get_query_history provide search reports. Other tools cover indexing, pages in search, links, sitemaps, and the recrawl queue.
Try it without an OAuth token
git clone https://github.com/tenqz/webmaster-mcp.git
cd webmaster-mcp
docker compose -f compose.demo.yml up -d --build
docker compose -f compose.demo.yml exec mcp /mcp-server --smoke http://127.0.0.1:8080/mcpThe demo uses synthetic data. Connect to http://localhost:8080/mcp with Authorization: Bearer demo-token. A successful smoke check here confirms the protocol and demo tools work. It does not verify access to a real Yandex account.
Configure a live installation
Stop the demo with docker compose -f compose.demo.yml down. Copy .env.example to .env, obtain an OAuth token with Webmaster access following the repository instructions, and set YANDEX_WEBMASTER_TOKEN. Set a separate MCP_AUTH_TOKEN for the MCP client, then start the live service:
docker compose up -d --build
docker compose exec mcp /mcp-server --smoke http://127.0.0.1:8080/mcpThe server does not implement an interactive browser OAuth login. The operator supplies the Yandex token. Mounted secrets are supported through YANDEX_WEBMASTER_TOKEN_FILE and MCP_AUTH_TOKEN_FILE. Do not configure both a file and the matching inline value. Use HTTPS when connecting from another machine.
Unknown is a meaningful diagnostic state
A useful agent request is: “Choose the host_id returned by list_hosts. Fetch summary and diagnostics. List PRESENT problems, show UNDEFINED checks separately, and state when the reports were collected.” It gives the answer an auditable basis instead of asking the model for a generic SEO verdict.
ABSENT means a particular problem is absent in that report. UNDEFINED does not establish that the check passed. Reports retain Yandex’s dates and field semantics. They should not be added to GSC figures as if the two systems measured precisely the same thing.
Recrawling is an explicit write operation
submit_recrawl is the only write tool. It queues a URL and consumes daily quota, without promising immediate indexing. Automated readers can set MCP_READ_ONLY=true. The tool is removed from discovery and direct calls are rejected as well. That configuration exposes 33 tools instead of the default 34.
Recrawl submissions are never retried automatically. When a request may have reached Yandex before the connection failed, outcome_unknown means its outcome is uncertain. Inspect the queue before deciding whether to submit again. Treating every timeout as a failed write can spend quota on a duplicate action.
Keep historical collection outside the adapter
The server provides access to reports. Scheduling, persistent observations, and comparisons with article changes belong in a separate collector. I use it alongside GSC MCP and ahref. Keeping those boundaries explicit prevents a failed source from silently becoming a zero in a combined report.
The result is a small interface an agent can inspect: which source was called, for which host, with which dates, and whether a state is known. That information is necessary before a recommendation deserves to influence a website change.
Webmaster MCP source code · Report contracts · What MCP does