yandex-mcp

一个 MCP 服务器，将 Yandex Webmaster、Yandex Direct 和 Yandex Metrika API 作为工具开放给 AI 助手（Claude Desktop、Claude Code、Cursor 等）。

它可以让 AI 助手直接用自然语言操作你的 Yandex SEO、广告和分析数据——检查搜索查询、管理索引和站点地图、申请重新抓取、运行诊断、在写入保护下管理 Direct 广告系列，以及提取流量 / 转化 / 广告统计——而你无需登录 Yandex Web 界面。

• 共 125 个工具：Webmaster 52 个，Direct 46 个，Metrika 25 个，项目管理 2 个。

• 6 个 MCP 提示（prompts）——基于 autostrategies 作战手册（playbook）构建的即用型工作流（广告系列审计、每周报告、广告系列上线、预算扩量、SEO 审计、学习检查），该作战手册也作为 yandex://playbook MCP 资源开放。

• 单服务器、多项目：一个 stdio 进程内支持多个 Yandex 账户/令牌。

• TypeScript / Node ≥ 22，基于 @modelcontextprotocol/sdk 和 zod 构建。

工作原理

src/index.ts 启动一个 McpServer，并注册来自 src/webmaster/ 和 src/direct/ 的所有工具组。所有请求都通过 src/client.ts——一个按项目定制的 HTTP 客户端——完成，它会：

• 附加 Authorization: OAuth <token> 请求头（Direct 使用 Bearer）；

• 将 Webmaster 请求路由到 api.webmaster.yandex.net，将 Direct 请求路由到 api.direct.yandex.com/json/v5（若启用了 direct.sandbox，则路由到 Direct Sandbox）；

• 解析并缓存 Webmaster 的 user_id，并在路径中注入 host_id；

• 在遇到网络错误 / 429 时进行指数退避重试，并处理 204 No Content；

• 展现 Direct 相关响应体中的 {"error": {...}}，并跟踪 Units 配额请求头。

Related MCP server: Yandex Wordstat MCP

前提条件

• Node.js ≥ 22。

• 拥有 Webmaster 和/或 Metrika API 访问权限的 Yandex OAuth 令牌。

获取 OAuth 令牌

1. 在 Yandex OAuth 控制台 注册一个应用，并授予 Webmaster（webmaster:hostinfo、webmaster:verify）和/或 Metrika（metrika:read / metrika:write）权限范围。

2. 通过 OAuth 流程 获取你账户对应的令牌。

注意：

• Direct 需要自己专属的应用权限范围，并在应用注册之后向 Direct 提交访问申请（заявка）并获得批准——现有的 Webmaster/Metrika 令牌如果不重新签发，则无法用于 Direct。在访问申请获批之前，请使用 Direct Sandbox（在项目配置中设置 direct.sandbox: true）。

• Webmaster 的 OAuth 令牌有效期为 6 个月，过期后必须重新签发。

设置

npm install
cp .env.example .env      # then put your token in .env
npm run build

.env:

YANDEX_OAUTH_TOKEN=your_oauth_token_here

运行

npm start          # runs dist/index.js (requires build)
npm run dev        # tsx watch mode against src/index.ts

该服务器通过 stdio 提供 MCP 服务，因此通常由 MCP 客户端启动，而非手动启动。

多项目配置

服务器可以提供服务给多个项目，每个项目都有各自的 Yandex 登录名/令牌。将 projects.example.json 复制为 projects.json（已加入 .gitignore）并填入内容，或将 YANDEX_PROJECTS_CONFIG 指向其他路径。如果不存在配置文件但设置了 YANDEX_OAUTH_TOKEN，则使用名为 default 的单个项目。

使用 yandex_set_active_project 切换活动项目，用 yandex_projects_list 查看项目，或向任意 Direct / Metrika 工具传入 project。Metrika 工具也会遵循项目配置中的 default_counter。

按项目的 Direct 设置：sandbox（路由到 Direct Sandbox）、client_login（代理账户）以及 limits——写入工具强制执行的最大预算/出价变更百分比。

连接到 MCP 客户端

令牌从 YANDEX_OAUTH_TOKEN 环境变量读取。

Claude Desktop / Cursor

添加到 MCP 服务器配置（claude_desktop_config.json 或等效文件）中：

{
  "mcpServers": {
    "yandex": {
      "command": "node",
      "args": ["/absolute/path/to/yandex/dist/index.js"],
      "env": {
        "YANDEX_OAUTH_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Claude Code

claude mcp add yandex --env YANDEX_OAUTH_TOKEN=your_token -- node /absolute/path/to/yandex/dist/index.js

工具

Webmaster（52）

所有工具名均以 yandex_webmaster_ 为前缀。

Direct（43）

所有工具名均以 yandex_direct_ 为前缀。写入工具会预览差异，除非设置 confirm: true，并执行分项目的预算/出价变更限制（可用 force: true 覆盖）。在项目中设置 direct.sandbox: true 可将调用路由至 Direct Sandbox。写入结果包含单条目汇总——Direct 会在成功的 HTTP 响应中上报部分失败，因此请检查 partial_failure。

项目管理（2）

yandex_projects_list、yandex_set_active_project——参见多项目配置。

Metrika（22）

所有工具名均以 yandex_metrika_ 为前缀。统计工具接受用于广告报告的 direct_client_logins（ym:ad: 指标——Direct 花费与站内行为数据连接）以及 extra_params 用于其他任何查询参数。

报告工具对应的是 Metrika 报告 API。指标与维度使用 ym:s:（会话数）和 ym:pv:（页面浏览量）命名空间，例如 metrics: "ym:s:visits,ym:s:users,ym:s:bounceRate"、dimensions: "ym:s:date,ym:s:lastTrafficSource"。日期支持 YYYY-MM-DD 或相对关键字（today、yesterday、7daysAgo）。若省略 counter_id/ids，将默认使用项目里设置的 default_counter。

Project layout

src/
  index.ts            # entry point: boots the MCP server, registers all tools
  client.ts           # per-project HTTP client (auth schemes, base URLs, retries, Direct transport)
  projects.ts         # project registry: per-project tokens, Direct config, limits
  server-tools.ts     # project management tools (list / set active)
  webmaster/          # 14 modules, 51 Webmaster tools
  metrika/            # management + Reporting API — 10 Metrika tools
  direct/             # read, guarded write, reports — 14 Direct tools

Scripts

许可证

MIT © Minas Sarkisyan