Skip to main content
Glama
yandex-direct-mcp

yandex-direct-mcp

by iarbor04

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 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 访问权限」。成功响应会显示登录名、账户货币和剩余点数。

我们踩过的坑

症状

原因

处理方法

error 58 —「注册未完成」,但申请已获批

令牌是在另一个应用下获取的,不是申请获批的那个。如果应用有多个,很容易踩坑

打开已获批的申请,核对 Client ID,用该应用获取令牌

沙箱中出现 error 58

沙箱同样要求申请获批

等待审批,没有变通办法

重新授权返回相同的令牌

在应用访问权限未被撤销前,Yandex 会返回已发放的令牌

在 id.yandex.ru/personal/data-access 撤销访问权限,然后重新授权

error 53 —「无效的 OAuth 令牌」

令牌已被撤销、过期或复制时被截断

通过 ./save-token.sh 重新获取

clients.get 正常响应,但 campaigns.get 返回空列表

令牌是在没有广告系列的登录名下获取的

在正确的登录名下获取令牌。无需重新申请:申请是针对应用而非用户获批的

重新创建应用后需要再次提交申请

审批与 Client ID 绑定,而非账户

不要删除已获批的应用。如果删了——重新提交申请,在描述中引用之前的 Client ID

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

工具

工具

用途

direct_status

是否有令牌、使用什么环境、访问是否可用(试调 clients.get)、剩余点数。不泄露令牌

direct_reference

速查表:服务、方法、params 示例、报告类型、出价单位、限制

direct_call

通用调用 POST /json/v5/{service},请求体为 {method, params}

direct_report

Reports API:发送 ReportDefinition,等待就绪(代码 201/202),返回 TSV

配置

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

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

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

环境变量

含义

YANDEX_DIRECT_TOKEN

直接指定令牌,优先级高于文件

YANDEX_DIRECT_CLIENT_LOGIN

代理账户的客户端登录名(Client-Login 请求头)

YANDEX_DIRECT_SANDBOX=1

使用沙箱

YANDEX_DIRECT_READONLY=1

阻止 add、update、delete、suspend、resume、moderate、set

YANDEX_DIRECT_CONFIG_DIR

其他配置目录

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

限额与费用

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

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

交互方案

与 Yandex Direct API 的交互方案

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

许可证

MIT——参见 LICENSE。

Available Tools

4 tools
direct_callA

Универсальный вызов Яндекс Директ API v5: POST на /json/v5/{service} с телом {method, params}. Покрывает всё управление: кампании, группы, объявления, ключевые фразы, ставки, ретаргетинг, справочники. Сначала загляни в direct_reference за именами сервисов, методов и формой params.

Inputs: method (required), service (required), params, sandbox, +1 more.

direct_referenceA

Шпаргалка по API v5: список сервисов, методов, примеры params, типы отчётов, единицы ставок и лимиты. Вызывай перед первым direct_call, чтобы не гадать с полями.

Inputs: no named parameters.

direct_reportA

Статистика через сервис Reports API v5. Принимает ReportDefinition в params, сам дожидается готовности отчёта (коды 201/202 с повторами) и возвращает TSV.

Inputs: params (required), sandbox, client_login, wait_seconds, +1 more.

direct_statusA

Проверить подключение к Яндекс Директу: найден ли токен, какая среда (боевая/песочница), доступен ли API (пробный clients.get) и сколько осталось баллов. Токен не раскрывается.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a clearly distinct role: status check, generic API call, report retrieval, and API reference. There is slight overlap because direct_call could theoretically hit report services or reference data, but the descriptions clearly separate async reports and reference lookups, so an agent can reliably choose the right tool.

    Naming Consistency5/5

    All tools share the 'direct_' prefix followed by a single concise word, creating a highly predictable and consistent naming scheme. The pattern is uniform and avoids mixed conventions or vague generic names.

    Tool Count5/5

    With 4 tools, the server is intentionally compact: a generic API call handles the long tail of operations, while status, report, and reference tools cover cross-cutting concerns. This is a well-scoped count for a broad but unified API surface.

    Completeness5/5

    The generic direct_call provides full coverage of all Yandex Direct API services and methods, so no CRUD operations are missing. direct_report adds proper handling of async report generation, and direct_reference closes the discoverability gap. The set is complete for its stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables managing Yandex Direct PPC campaigns, ad groups, ads, and keywords, plus pulling performance statistics via the Yandex Direct API v5.
      46
      641 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables interaction with Yandex advertising and analytics APIs (Direct, Metrika, Audience, Webmaster, AdMetrica) through MCP tools, resources, and prompts for campaign management and data retrieval.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.
      2
      1
      MIT