yandex-direct-mcp
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 访问权限」。成功响应会显示登录名、账户货币和剩余点数。
我们踩过的坑
症状 | 原因 | 处理方法 |
| 令牌是在另一个应用下获取的,不是申请获批的那个。如果应用有多个,很容易踩坑 | 打开已获批的申请,核对 Client ID,用该应用获取令牌 |
沙箱中出现 | 沙箱同样要求申请获批 | 等待审批,没有变通办法 |
重新授权返回相同的令牌 | 在应用访问权限未被撤销前,Yandex 会返回已发放的令牌 | 在 id.yandex.ru/personal/data-access 撤销访问权限,然后重新授权 |
| 令牌已被撤销、过期或复制时被截断 | 通过 |
| 令牌是在没有广告系列的登录名下获取的 | 在正确的登录名下获取令牌。无需重新申请:申请是针对应用而非用户获批的 |
重新创建应用后需要再次提交申请 | 审批与 Client ID 绑定,而非账户 | 不要删除已获批的应用。如果删了——重新提交申请,在描述中引用之前的 Client ID |
另外:不要将令牌粘贴到代理聊天中——它会留在聊天记录里。这正是 save-token.sh 使用隐藏输入的原因。如果已经粘贴了——在 id.yandex.ru/personal-data-access 撤销访问权限并获取新令牌。
工具
工具 | 用途 |
| 是否有令牌、使用什么环境、访问是否可用(试调 |
| 速查表:服务、方法、 |
| 通用调用 |
| Reports API:发送 ReportDefinition,等待就绪(代码 201/202),返回 TSV |
配置
~/.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。
Available Tools
4 toolsdirect_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
MCP for Yandex Direct: manage ad campaigns & analytics from Claude or ChatGPT
Review Yandex Direct reports and manage supported campaign settings in ChatGPT.
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
Google Ads for AI agents: live reports, Keyword Planner, and changes with preview, confirm and undo.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables managing Yandex Direct PPC campaigns, ad groups, ads, and keywords, plus pulling performance statistics via the Yandex Direct API v5.46641 npm10MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityAmaintenanceAn MCP server that gives AI agents direct access to the Yandex Direct API to manage campaigns, groups, ads, keywords, bids, and reports via natural language.117 npm6Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.21MIT