yandex-direct-mcp

用于 Yandex Direct API v5 的 MCP 服务器。将广告账户连接到 AI 代理（Claude Code、Cursor 以及任何其他 MCP 客户端）：用普通文本提出任务，代理自行组装所需的 API 调用并解析响应。

Ты:    посмотри, куда за август ушёл бюджет и что откручивается без конверсий
Агент: [direct_report] → 12 кампаний, 340 фраз
       Расход 214 800 ₽. Кампания «Поиск / Бренд» — 38%, CPA 610 ₽.
       17 фраз потратили 31 400 ₽ при нуле конверсий — вот они, отключаем?

无依赖：一个 Node.js 文件，stdio 传输，通过内置 fetch 发起请求。

• 令牌本地存储在权限为 600 的文件中，除 api.direct.yandex.com 外不会发送到任何地方。

• 修改需确认。 MCP 客户端会对每次调用请求许可；此外还有「只读」模式，可在服务器层面阻止修改类方法。

• 完整 API，而非子集。 通用工具 direct_call 覆盖 v5 的所有服务——从 campaigns 到 keywordsresearch。

可以做什么

数据分析。 按任意维度和时间段生成报告：广告系列、广告组、广告、关键词、搜索查询、地域、设备、时段、性别和年龄。花费、点击、CTR、CPC、转化、CPA、周期对比。分析搜索查询中的垃圾词，查找有花费但无转化的关键词。

管理。 创建和编辑广告系列、广告组、广告、关键词。出价和每日预算——包括批量操作，按规则执行（「CPA 超过 2000 卢布 → 出价下调 20%」）。否定关键词、启用和暂停、提交审核、按地域/设备/受众调整出价、再营销。

语义。 关键词频次查询（keywordsresearch）、地区和时区字典（dictionaries）。

定期任务。 每日早晨的昨日花费汇总、每周搜索查询分析、超支提醒——如果 MCP 客户端支持定时任务。

带请求示例的详细场景：docs/usage.md。

Related MCP server: Yandex Direct MCP Server

要求

• Node.js 18 或更高版本（需要内置 fetch）。

• Yandex Direct 账户。

• 在 oauth.yandex.ru 注册的应用 且 API 访问申请已获批。这是最大的门槛，需要一小时到三天——先从这里开始：docs/registration.md。

安装

git clone https://github.com/iarbor04/yandex-direct-mcp.git
cd yandex-direct-mcp

无依赖，不需要 npm install。

Claude Code：

claude mcp add yandex-direct --scope user -- node "$PWD/server.js"

Cursor、Windsurf 以及其他使用 JSON 配置的客户端：

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/абсолютный/путь/yandex-direct-mcp/server.js"]
    }
  }
}

工具会在客户端启动时出现——添加服务器后请重启会话。

授权

顺序很重要。如果不按此顺序操作，会收到错误 58 并浪费时间——我们就是这样踩过坑的。

1. 申请 API 访问权限

在 oauth.yandex.ru 注册应用，然后在 Direct 界面提交申请：「我的申请」。审核时间为俄罗斯工作日 10:00 至 19:00，需要一小时到三天，高峰期最长七天。

表单中写什么（所有字段的现成文案，包括交互方案描述和图表）——docs/registration.md。

没有获批的申请，连沙箱都无法使用。 已验证：api-sandbox.direct.yandex.com 返回的错误 58 与生产 API 相同。「先用测试数据调试」是行不通的。

2. 令牌

./save-token.sh <CLIENT_ID>

脚本会显示授权链接，等待你粘贴重定向后的地址栏内容（输入为隐藏模式——URL 和令牌都不会进入 shell 历史），提取 access_token，放入 ~/.config/yandex-direct/token（权限 600），并立即运行访问检查。

<CLIENT_ID> 是 申请获批的那个应用 的标识符。脚本会将其保存在 config.json 中，之后可以不带参数运行。

手动操作也一样：打开 https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>，从地址栏中 #access_token=（到 & 为止）之后取出令牌，放入文件。

3. 验证

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"direct_status","arguments":{}}}' \
  | node server.js

或者直接问代理：「检查 Direct 访问权限」。成功响应会显示登录名、账户货币和剩余点数。

我们踩过的坑

另外：不要将令牌粘贴到代理聊天中——它会留在聊天记录里。这正是 save-token.sh 使用隐藏输入的原因。如果已经粘贴了——在 id.yandex.ru/personal-data-access 撤销访问权限并获取新令牌。

工具

配置

~/.config/yandex-direct/config.json：

{
  "token": "",
  "client_id": "…",
  "client_login": "",
  "sandbox": false
}

每次调用时都会读取令牌——替换后无需重启服务器。

令牌查找顺序：YANDEX_DIRECT_TOKEN → config.json → ~/.config/yandex-direct/token。

限额与费用

每次调用都会消耗点数（Units）；剩余点数在响应头中返回，并打印在结果顶部。普通 get 约 10 点，报告更贵。每日限额取决于账户（普通客户约 160 000 点，日常使用绰绰有余）。

get 方法每次最多返回 10 000 个对象——之后通过 LimitOffset 分页。出价以微单位设置：30000000 = 30 卢布。报告的 ReportName 必须唯一，否则 Direct 会返回之前生成的报告。

交互方案

源文件：docs/scheme.html——如果需要为申请制作自己的图片版本，可以参考。

许可证

MIT——参见 LICENSE。