Yandex Direct MCP

yandex-direct-mcp

适用于 Yandex Direct API v5 的 MCP 服务——可管理广告系列、广告组、广告、关键词、出价、出价调整、附加链接、虚拟名片和报告。共 43 个工具。

可写入，无试运行模式。 与此单仓库中的其他服务不同，这个服务会修改线上广告数据：它可以创建、更新、删除和归档广告系列与广告，也可以设置出价（单位为微单位——出错 1,000,000 倍的风险确实存在）。没有确认步骤，也没有试运行模式。在你信任该工作流之前，请将其指向沙盒（YANDEX_DIRECT_SANDBOX=true）。

安装

此软件包以 @stufently/yandex-direct-mcp 发布；公共注册表上不带作用域的 yandex-*-mcp 名称属于无关的发布者（请参阅根 README 中的说明）。该作用域下目前还没有发布内容，因此请从源代码运行：

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

配置

变量	必填	说明
YANDEX_DIRECT_TOKEN	是	Direct API v5 的 OAuth 令牌
YANDEX_DIRECT_CLIENT_LOGIN	仅代理商需要	要代表其操作的客户端登录名
YANDEX_DIRECT_SANDBOX	否	true 会将调用路由到 Direct 沙盒

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

工具

类别	工具
广告系列	get_campaigns、add_campaigns、update_campaigns、delete_campaigns、archive_campaigns、unarchive_campaigns、suspend_campaigns、resume_campaigns
广告组	get_adgroups、add_adgroups、update_adgroups、delete_adgroups、archive_adgroups、unarchive_adgroups
广告	get_ads、add_ads、update_ads、delete_ads、archive_ads、unarchive_ads、moderate_ads
关键词	get_keywords、add_keywords、update_keywords、delete_keywords、suspend_keywords、resume_keywords
出价	get_keyword_bids、set_keyword_bids、set_auto_keyword_bids、get_bid_modifiers、add_bid_modifiers、set_bid_modifiers、delete_bid_modifiers
扩展	get_sitelinks、add_sitelinks、delete_sitelinks、get_vcards、add_vcards、delete_vcards
其他	create_report、get_dictionaries、get_clients

不可逆工具需要 confirm: true

有十四种工具无法通过此 API 撤销，而且这是唯一一个误操作会花掉真金白银的服务。除非调用中带有 confirm: true，否则这些工具会拒绝执行：

类别	工具	无法撤销的原因
删除	delete_campaigns、delete_adgroups、delete_ads、delete_keywords、delete_bid_modifiers、delete_sitelinks、delete_vcards	实体及其关联统计数据都会消失；add_* 会创建带有新 ID 的新实体，而不是恢复原来的实体
更新	update_campaigns、update_adgroups、update_ads、update_keywords	字段会被就地覆盖，而 Direct 不会公开修订历史，因此无法读取之前的广告文案、预算或策略
出价	set_keyword_bids、set_auto_keyword_bids、set_bid_modifiers	同样是覆盖操作，但会涉及金钱：这些数值决定账户每次点击要支付多少费用

{ "ids": [12345], "confirm": true }

未携带该参数调用时，工具会返回错误结果，且不会向 Direct API 发送任何内容——不会触及任何实体，不会更改任何出价，也不会消耗 API 单位：

Refused: `delete_campaigns` requires explicit confirmation.

Target — IDs: 12345. Deleting campaigns is irreversible: they and their accumulated statistics
are gone for good, and Yandex Direct offers no way to restore them.

Nothing was sent to the Yandex Direct API — no campaign, ad, keyword or bid was touched, and no
API units were spent.

To go ahead, call `delete_campaigns` again with the same ids and `confirm: true`.
To see the current state first, call `get_campaigns`.

在 JSON 架构中，confirm 特意设为可选项：缺少确认时必须返回上述说明，而不能返回模型无法处理的架构验证错误。只有字面值 true 才有效——"true"、1 和 "yes" 都会被拒绝，因为猜测协议不等于决定花钱。这十四种工具在 MCP 注释中都带有 destructiveHint: true，因此能够展示工具风险的客户端可以在调用前显示提示。

add_*、archive_*/unarchive_*、suspend_*/resume_* 和 moderate_ads 刻意不设防护。 它们在同一服务中都有对应的逆向操作（或者对 moderate_ads 而言，不会触及实体本身），因此这些操作只是变更，而不是损失。若为每次写入都设置防护，调用者就会养成下意识传入 confirm: true 的习惯——这恰恰会让真正重要的十四种调用失去防护作用。

出价以微单位表示（×10⁶）。试用时请设置 YANDEX_DIRECT_SANDBOX=true。

已知限制

• API 路径硬编码为 /json/v5，因此无法访问统一效果广告系列端点（v501）。
• 不会展示 Units 响应标头（已消耗／剩余点数），因此客户端无法查看某次调用消耗了多少配额。

许可证

MIT