Yandex Webmaster MCP

yandex-webmaster-mcp

用于 Yandex Webmaster API v4 的 MCP 服务。监控网站健康状况、索引状态、搜索查询、反向链接、站点地图等。

安装

此软件包以 @stufently/yandex-webmaster-mcp 发布；非作用域名称 yandex-webmaster-mcp 属于无关的发布者（参见根目录 README 中的说明）。 目前该作用域下尚无内容，因此请从源代码运行：

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp && bun install
node packages/yandex-webmaster-mcp/src/index.mjs

配置

添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-webmaster-mcp/src/index.mjs"],
      "env": {
        "YANDEX_WEBMASTER_TOKEN": "your-oauth-token"
      }
    }
  }
}

环境变量

变量	必填	说明
YANDEX_WEBMASTER_TOKEN	是	Webmaster API 的 OAuth 令牌
YANDEX_CLIENT_ID	用于授权流程	Yandex OAuth 应用客户端 ID
YANDEX_CLIENT_SECRET	用于授权流程	Yandex OAuth 应用客户端密钥

身份验证

要以交互方式获取 OAuth 令牌：

node packages/yandex-webmaster-mcp/src/index.mjs auth

此操作会打开浏览器进行 Yandex OAuth 授权，并返回令牌。将令牌设置为 YANDEX_WEBMASTER_TOKEN。

注意：Webmaster API 使用 Authorization: OAuth {token}（而不是 Bearer）。

Agent 操作手册

与此文件同目录的 SKILL.md 是供 Agent 使用的任务级指南：新站点流程、常规审计顺序、重新抓取规则、三种不同时间序列的读取方法，以及——重要的是——API v4 不具备的功能（IndexNow、robots.txt、站点区域、网站图标、移动设备状态、Metrika 绑定），以免凭空捏造。

工具参考（33 个工具）

核心（3）

工具	说明	参数
get-user	获取当前 Webmaster 用户信息和 user_id	--
list-hosts	列出所有主机（网站），包括其 host_id——其他所有工具都需要此标识符	--
get-host	获取特定主机的详细信息	host_id

统计（2）

工具	说明	参数
get-summary	获取网站摘要：SQI、页面计数、问题	host_id
get-sqi-history	获取 SQI（网站质量指数）历史记录	host_id、date_from?、date_to?

诊断（1）

工具	说明	参数
get-diagnostics	获取网站诊断信息和问题	host_id

搜索查询（2）

工具	说明	参数
get-popular-queries	获取网站的热门搜索查询	host_id、order_by（TOTAL_SHOWS/TOTAL_CLICKS）、device_type?、date_from?、date_to?、limit?（1-500，默认值：100）、offset?
get-query-history	获取搜索查询总量历史记录	host_id、device_type?、date_from?、date_to?

索引（4）

工具	说明	参数
get-indexing-history	获取索引历史记录	host_id、date_from?、date_to?
get-indexing-samples	获取已索引 URL 示例	host_id、limit?（1-100）、offset?
get-insearch-history	获取搜索结果中出现情况的历史记录	host_id、date_from?、date_to?
get-insearch-samples	获取出现在搜索结果中的 URL 示例	host_id、limit?（1-100）、offset?

搜索事件（3）

工具	描述	参数
get-search-events-history	获取搜索 URL 事件历史记录	host_id、date_from?、date_to?
get-search-events-samples	获取搜索事件的示例 URL，并提供每个 URL 的排除原因（excluded_url_status）：包含已获取页面的 exclusion_reasons 统计，以及 URL → 原因的 excluded_pages 列表	host_id、event_type?（APPEARED_IN_SEARCH/REMOVED_FROM_SEARCH——客户端筛选，API 不支持）、limit?（1-100，默认值：10）、offset?
get-excluded-pages	在时间窗口内从搜索结果中移除的页面，并提供每个页面的 excluded_url_status。 根据 REMOVED_FROM_SEARCH 事件生成，每个 URL 去重（保留最新事件），因此重新出现的页面会列在 returned_to_search 中。逐页遍历混合事件流，直到收集到 limit 个排除页面，然后报告 next_offset（第一个未读取的事件）/exhausted，以便继续遍历。还会返回 summary_excluded_pages_count，供交叉核对	host_id、limit?（排除页面数量，1-100，默认值：20）、offset?、max_requests?（页面获取次数，1-50，不计重试，默认值：10）、returned_urls?（继续遍历时，传入上次的 returned_to_search）

API v4 中没有专门的“排除页面”资源：get-summary 仅提供聚合的 excluded_pages_count，而某个 URL 被移除的原因记录在 /search-urls/events/samples 的 REMOVED_FROM_SEARCH 事件中。由于 API 不支持服务端事件筛选，count 仍会统计两种类型的事件，而 limit/offset 会分页读取混合事件流。get-search-events-samples 会报告其中一页的内容； get-excluded-pages 会负责遍历，因此它的 limit 统计的是排除页面，而不是 事件。除了状态码之外，每个 URL 的详细信息还包括：HTTP_ERROR 对应的 bad_http_status，以及重定向目标、规范地址或重复项对应的 target_url。

这些是按时间排列的事件，并非索引快照。 同一 URL 可能先出现 REMOVED_FROM_SEARCH，之后又出现 APPEARED_IN_SEARCH——它曾被移除，后来又重新出现，因此目前仍在搜索结果中。因此，get-excluded-pages 会按 URL 去重并保留最新事件：最新事件为重新出现的 URL 会进入 returned_to_search，而不是 pages。有两点值得特别说明：

• 扫描窗口之前发生的排除事件不会显示，无论它现在看起来有多新；
• 去重范围仅限单次调用。从 next_offset 继续遍历时，状态会被清空，因此，如果某个页面是在上一个窗口内重新出现的，它会再次被报告为已排除——将之前的 returned_to_search 传入 returned_urls，以确保遍历结果准确；
• get-summary 返回的 excluded_pages_count 与 pages 的长度是两种不同类型的数字，不应期望二者相等。工具会将聚合值作为 summary_excluded_pages_count 返回，并在文本中明确说明，避免读者自行发现两者相差 25 倍。

每个 URL 的状态字段在所有位置都命名为 excluded_url_status——包括工具 描述、get-search-events-samples 的 excluded_pages，以及 get-excluded-pages 的 pages。它沿用了 Yandex 参考文档中的名称 （ApiExcludedUrlStatus），因此可以直接在文档中搜索。

链接（4）

工具	描述	参数
get-external-links	获取指向该网站的外部链接	host_id、limit?（1-100）、offset?
get-external-links-history	获取外部链接数量历史记录	host_id、date_from?、date_to?
get-broken-internal-links	列出失效的内部链接：目标 URL、链接到该 URL 的来源页面，以及 Yandex 上次检查该链接的时间。记录包含 days_since_last_check、never_rechecked 和 stale（上次检查距今超过 90 天）	host_id、limit?（1-100）、offset?
get-broken-internal-links-history	获取失效内部链接数量历史记录	host_id、date_from?、date_to?

失效链接记录是 Yandex 上次检查该链接时的快照，而这个时间点可能已经过去数月：当 source_last_access_date 等于 discovery_date 时，自发现问题后就没有再次验证过该链接，因此它可能早已修复。每条记录都会包含 days_since_last_check、never_rechecked 和 stale（上次检查距今超过 90 天——仅有 never_rechecked 不会将其设为 stale），文本块也会将警告放在列表上方。对这些网站报告的 258 个链接进行实时检查（2026-09-02），发现其中有 10 个是真正的 404；约 80% 是 301 重定向。API 并没有谎报——只是旧版的单行输出让这个数量看起来像是服务中断。

⚠️ 在 Yandex 参考文档中，source_last_access_date 的名称与描述不一致：名称指的是 source，描述却说“机器人上次访问链接目标页面的日期”。这里的措辞保持中立（“上次检查”），因为无论按哪种理解，对记录时间的判断都成立，但针对特定页面的判断则不成立。

站点地图（4）

工具	描述	参数
get-sitemaps	列出主机的所有站点地图	host_id、limit?（1-100）
get-sitemap	获取特定站点地图的详细信息	host_id、sitemap_id
get-user-sitemaps	列出用户添加的站点地图	host_id、limit?（1-100）
add-sitemap	**写入。**添加用户站点地图文件；返回 sitemap_id。此操作仅添加文件，可在 Webmaster 面板中移除	host_id、url

add-sitemap 要求主机已通过验证（否则返回 404 HOST_NOT_VERIFIED）。添加已存在的文件会返回 409 SITEMAP_ALREADY_ADDED；与这里所有其他非 2xx 响应一样，该响应会作为错误呈现，且其负载会提供已有的 sitemap_id——应将其理解为“已存在”，而不是重试。API 支持移除站点地图（DELETE /user-added-sitemaps/{id}），但这里刻意没有封装此操作。

重要 URL（2）

工具	描述	参数
get-important-urls	获取网站的重要 URL	host_id、limit?（1-100）、offset?
get-important-url-history	获取特定重要 URL 的历史记录	host_id、url、date_from?、date_to?

重新抓取（4）

工具	描述	参数
get-recrawl-quota	获取重新抓取配额（每日限额和剩余量）	host_id
add-recrawl-url	**写入。**将 URL 加入重新抓取队列；会消耗每日配额	host_id、url
get-recrawl-queue	列出已提交的重新抓取任务及其状态	host_id、limit?（默认值：10）、offset?
get-recrawl-task	获取单个重新抓取任务的状态	host_id、task_id

站点管理（4）

这些操作会修改你的 Webmaster 账号，而不只是读取其中的数据。

工具	描述	参数
add-host	写入。 将站点添加到 Webmaster（之后需要验证）。可通过 delete-host 撤销	host_url（包含协议）
verify-host	获取验证状态和适用的验证方法	host_id
start-verification	写入。 开始所有权检查（POST …/verification，无请求体）。verification_uin 必须已放置在站点上；检查是异步的，请轮询 verify-host。可撤销	host_id、verification_type（HTML_FILE / META_TAG / DNS）
delete-host	写入。 从 Webmaster 中移除站点。不可撤销——参见删除站点。需要 confirm: true	host_id、confirm

删除站点

delete-host 是此处唯一不可撤销的工具，只有调用中包含 confirm: true 才会执行：

{ "host_id": "https:example.com:443", "confirm": true }

如果未提供该参数，工具会返回错误结果，且不会向 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-host` again with host_id https:example.com:443 and `confirm: true`.
To check which site this host ID stands for first, call `get-host-info` or `list-hosts`.

JSON 架构中有意将 confirm 设为可选：缺少确认时，必须返回上述说明，而不是模型无法处理的架构验证错误。只有字面值 true 才算确认——"true"、1 和 "yes" 都会被拒绝，因为猜测协议并不等于决定删除任何内容。该工具在 MCP 注解中还标记为 destructiveHint: true，因此能够展示工具风险的客户端可以在调用前将其显示出来。

另外三个写入操作特意不设保护：add-host 是添加操作，可通过 delete-host 撤销；add-recrawl-url 只会将 URL 加入重新抓取队列，并消耗每日配额（配额会补充）；add-sitemap 会添加一个仍可移除且不会留下历史记录的文件。 如果每次写入都要求确认，调用方就会养成反射式传入 confirm: true 的习惯，而这恰恰会让它在唯一重要的调用中失去作用。

通用参数

• host_id -- 站点标识符，经过 URL 编码（例如，https:example.com:443）。通过 list-hosts 获取。
• date_from、date_to -- YYYY-MM-DD 格式的日期。会严格验证（不会静默溢出日期）。
• limit、offset -- 分页控制参数。
• device_type -- 以下值之一：ALL、DESKTOP、MOBILE、TABLET、MOBILE_AND_TABLET。

缓存

user_id 会在首次 API 调用时获取一次，并在会话期间缓存。发生 401/403 错误时会自动失效。

许可证

MIT