Яндекс Директ MCP

Яндекс Директ MCP 将 AI 应用连接到 Яндекс Директ 广告账户。您可以用自然语言询问广告预算的去向，关联查看广告系列、广告组和关键词，然后直接在对话中准备或执行所需修改，无需在账户各板块之间切换。连接直接在对话中开始：无需提前创建令牌或编辑配置。

• 44 个工具。 广告系列、广告组、广告、关键词、出价、调整、附加信息、统计、余额、参考手册以及直接在对话中连接账户。

• 两种连接方式。 通过 URL 的远程服务器无需手动获取令牌，且只读取数据；通过 npx 的本地服务器可对账户进行完全访问。

• 在聊天中连接。 Яндекс 会打开登录页面；从聊天中获取代码后即可立即操作广告，访问权限会自动续期。

• 金额一目了然。 在便捷工具中，预算、出价和余额以账户货币显示，而非 API 的微单位。

• 真实广告。 本地修改会应用到真实账户，可能影响实际花费。如需在测试环境中操作，可使用 Яндекс Директ 沙箱。

试试第一条消息：

显示我账户的广告系列以及上周按广告组统计的花费。

连接服务器 · 查看可执行的任务 · 打开技术文档

一分钟了解工作方式

您： 连接 Яндекс Директ。

助手： 提供 Яндекс 登录链接。请使用有权限访问目标广告账户的账号打开链接，确认授权后把显示的代码发给我。

您： 发送 Яндекс 页面上的代码。

助手： 连接 Директ 并显示账户。无需重启应用。

您： 显示我账户的广告系列以及上周按广告组统计的花费。

助手： 找到广告系列，按广告组生成报告，并以账户货币显示花费。

Related MCP server: Yandex Direct MCP Server

目录

• 快速开始

• 可以委托什么

• 工作原理

• 哪些操作会修改数据

• 连接与配置

• 数据与遥测

• 限制

• 技术文档

• 支持

快速开始

1. 选择连接方式，并按下方说明将服务器添加到 AI 应用。

2. 打开新对话并询问：「显示我账户的广告系列以及上周按广告组统计的花费」。

无需自行获取令牌的分析 — 通过 URL

远程服务器 https://mcp.askads.ru/mcp 可通过支持按 URL 连接 MCP 的应用进行连接。在浏览器中登录 Яндекс 并确认授权：无需在配置中传递令牌。此模式仅用于读取 — 统计、审计和查看对象；不会修改广告设置。

在 Claude Code 中可通过以下命令添加：

claude mcp add --transport http yandex-direct https://mcp.askads.ru/mcp

连接后打开 /mcp 完成授权。在其他支持 HTTP MCP 的应用中，通过应用界面添加相同的 URL。

完全访问 — 通过 npx 本地运行

创建和修改对象需要 Node.js 20+。npx 会在首次运行时下载服务器 — 无需单独安装包。无需提前获取令牌 — 连接直接在对话中开始：

1. 将服务器添加到 AI 应用 — 下方以 Codex 为例，其他应用收录在可折叠说明中。

2. 输入：「连接 Яндекс Директ」— 助手会引导您完成 Яндекс 登录并显示账户。

用于 CI 和代理环境 — 使用现成令牌和 YANDEX_DIRECT_LOGIN，参见 连接与配置。

通过应用界面：

1. 打开 Settings → Plugins → MCP servers。

2. 点击 Add server。

3. 添加启动命令 npx -y mcp-yandex-direct@latest。

通过命令行：

codex mcp add yandex-direct -- npx -y mcp-yandex-direct@latest

检查连接：

codex mcp list

Codex 官方说明

claude mcp add --transport stdio --scope user yandex-direct -- npx -y mcp-yandex-direct@latest

检查连接：claude mcp list。

打开 Settings → Developer → Edit Config，在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

如果没有 Developer 部分，请手动打开文件：macOS — ~/Library/Application Support/Claude/claude_desktop_config.json，Windows — %APPDATA%\Claude\claude_desktop_config.json。重启 Claude Desktop。

打开 ~/.cursor/mcp.json 以在所有项目中连接服务器，或在特定项目中打开 .cursor/mcp.json。添加：

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

在命令面板中执行 MCP: Open User Configuration。在打开的 mcp.json 中添加服务器：

{
  "servers": {
    "yandex-direct": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

保存后执行 MCP: List Servers，并从列表启动服务器。

可以委托什么

检查预算花费情况

• 「上周哪些广告系列花费最多？」

• 「哪些广告获得了展示和点击，但没有产生转化？」

• 「比较各广告系列一个月的花费、CTR 和平均点击价格」。

• 「显示账户余额和 API 每日配额剩余量」。

寻找优化点

• 「哪些关键词在消耗预算，但没有带来点击？」

• 「哪些广告组和广告目前处于暂停状态或未通过审核？」

• 「检查当前对移动设备生效的出价调整」。

• 「这个广告系列有哪些快速链接和补充说明？」

准备修改

• 「为高 CTR 的关键词建议新出价，并在应用前显示修改内容」。

• 「检查广告系列中是否包含该主题的否定关键词，并准备列表」。

• 「为莫斯科收集新文字广告系列的参数：预算、广告组、关键词和广告」。

执行明确操作

• 「将以下关键词添加到广告组 123，并设置出价 45 ₽」。

• 「暂停广告 456」。

• 「将带图片的页面发送到广告库」。

工作原理

广告通常由三个层级构成：广告系列 → 广告组 → 广告。广告组中包含关键词、展示设置和出价调整。广告可以包含快速链接、补充说明、名片和图片。

服务器帮助您将这些对象关联起来查看：将广告系列的花费与广告组统计、关键词和广告关联。它只能创建文字类型的广告系列和广告。其他类型的广告系列可以读取、重命名、修改预算、暂停、归档和按 ID 删除。

统计数据并非即时生成：get_statistics 会在 Reports 服务中启动报告并等待其完成。大型列表由 autoPaginate 自动翻页获取。

哪些操作会修改数据

通过 URL 的远程服务器只读取数据。通过 npx 的本地服务器可以修改真实广告账户：

工具会向 AI 应用传递读取、写入和潜在不可逆操作的标记。应用可能会显示确认提示，但其行为取决于客户端。直接 API 请求在未设置 confirmWrite=true 时不会执行写入；修改广告需要明确的请求。

连接与配置

常规使用无需提前获取令牌：

1. 在聊天中请求连接 Яндекс Директ。

2. 打开 Яндекс OAuth 链接 使用有权限访问目标广告账户的账号。

3. 确认授权，并将显示的代码发送到聊天中。完成，即可操作广告：无需重启客户端，也无需修改配置。

之后连接会自动维持：访问权限自动续期，不会一年后失效。检查状态 — 请求「显示连接状态」，断开 — 「断开 Директ」。已授予的权限可在 Яндекс ID 中撤销。

对于没有对话的 CI 和自动安装环境，可通过环境变量进行配置：

可通过以下链接获取用于 YANDEX_DIRECT_TOKEN 的现成令牌，使用有权限访问目标账户的账号登录：

获取 Яндекс Директ 令牌

请勿在聊天、代码仓库和截图中发布令牌：它可以访问广告账户，包括可能影响预算的操作。

数据与遥测

默认情况下，服务器会发送匿名技术事件：随机安装标识符、所调用工具的名称、服务器、AI 应用、Node.js 和操作系统的版本。这是为了了解服务器的哪些部分被使用，以及启动时是否出现问题。Yandex 令牌、广告账户数据、工具参数、请求文本、环境变量的值和名称不会被发送。

要为 Ask Ads MCP 服务器禁用遥测，请设置环境变量：

ASKADS_TELEMETRY=0

限制

• 每日 API 配额。 每次调用都会消耗 Units。get_quota 工具显示今天已消耗、剩余和可用的额度。

• 报告限制。 Yandex 报告对每日数量和容量有自己的限制，而且需要等待 Reports 服务中的报告就绪。

• 大列表。 如果在自动分页时达到内部限制，服务器会明确将结果标记为不完整，而不是隐藏这一点。

• 临时错误。 在频率限制时，服务器最多重试三次。网络和服务器错误仅对只读操作自动重试，以避免重复更改。

• 生产账户。 本地更改会应用到真实的广告账户，并可能影响支出。测试时请使用沙箱（YANDEX_DIRECT_SANDBOX=true）。

• 无持续监控。 服务器仅在 AI 应用调用期间运行。如果应用支持定期任务，可以配置周期性请求来检查所需指标。

技术文档

• MCP 功能目录 — 每个工具的用户任务页面。

• 所有工具 — 每个工具的参数、响应和限制。

• 开发 — 项目结构和源代码工作。

• Yandex Direct API — API 及其限制的原始来源。

• npm 包 — 已发布的服务器版本。

支持

发现错误或缺少场景？创建 issue 或通过 Telegram 联系我们。