Yandex Direct MCP
Yandex Direct MCP lets an AI client connect to and manage Yandex Direct advertising accounts, from authentication and reporting to campaign, ad, keyword, bid, and extension changes.
Connect and authenticate: check connection status, start/finish OAuth login, log out, and support token-based CI setup.
Inspect accounts and clients: get account details, balance, API quota, agency clients, and multi-client overviews.
Manage campaigns: list, create text campaigns, update names/dates/negative keywords, change strategies and weekly budgets, suspend/resume/archive/delete.
Manage ad groups: list, create, update, and delete groups; manage group negative keywords.
Manage ads: list, create, update, moderate, suspend/resume, archive, and delete ads.
Manage keywords and bids: list/add keywords, suspend/resume/delete them, and set search/network bids.
Manage targeting and exclusions: read/write excluded sites, bid modifiers for devices/demographics/retargeting/regions, and look up regions/dictionaries.
Manage extensions and assets: sitelinks, callouts, ad images, videos, and creatives.
Run reports: request Yandex Direct statistics by campaign, ad group, ad, criteria, search query, or custom report, including period comparisons and filters.
Use raw API access: call any Yandex Direct v5 service/method, requiring
confirmWrite=truefor write methods.Work across agency clients: most tools accept
client_loginto operate on a selected client account.
Write tools can modify a live ad account and affect spend unless sandbox mode is enabled.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Yandex Direct MCP list my active campaigns"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Yandex Direct MCP
Yandex Direct MCP connects an AI app to your Yandex Direct advertising account. Ask in plain language where your ad budget is going, compare campaigns, ads, and keywords, then prepare or make the changes you need without switching between account sections. Setup starts right in the conversation: no need to create a token or edit configuration in advance.
44 tools. Campaigns, ad groups, ads, keywords, bids, adjustments, extensions, statistics, balance, reference books, and account connection right in the conversation.
Two ways to connect. A remote server by URL requires no manual token retrieval and is read-only; a local one via
npxgives full access to the account.In-chat connection. Yandex opens a sign-in page; after the code from the chat you can start working with ads right away, and access is renewed automatically.
Money in a readable format. Convenient tools show budgets, bids, and balance in the account currency rather than API micro-units.
Real advertising. Local changes are applied to the live account and can affect spending. For testing, Yandex Direct sandbox is available.
Try it with your first message:
Show me the campaigns in my account and last week's spend by ad group.
Connect the server · See scenarios · Open technical documentation
See it working in a minute
You: Connect Yandex Direct.
Assistant: Gives you a link to sign in to Yandex. Open it under the account with access to the desired advertising account, confirm access, and send back the code shown.
You: Sends the code from the Yandex page.
Assistant: Connects Direct and shows the account. No need to restart the app.
You: Show me the campaigns in my account and last week's spend by ad group.
Assistant: Finds the campaigns, builds a report by ad group, and shows spend in the account currency.
Related MCP server: Yandex MCP Server
Table of contents
Quick start
Choose a connection method and add the server to your AI app using the instructions below.
Open a new conversation and ask: "Show me the campaigns in my account and last week's spend by ad group."
Analysis without getting a token yourself — by URL
The remote server https://mcp.askads.ru/mcp connects through an app that supports MCP by URL. Sign in to Yandex in your browser and confirm access: no token needs to be passed in the config. This option is read-only — for statistics, audits, and viewing objects; it does not change ad settings.
In Claude Code you can add it with the command:
claude mcp add --transport http yandex-direct https://mcp.askads.ru/mcpAfter connecting, open /mcp and complete authorization. In other apps that support HTTP MCP, add the same URL through the app interface.
Full access — locally via npx
Creating and modifying objects requires Node.js 20+. npx downloads the server on first launch — no separate package installation needed. No need to obtain a token in advance — connection starts right in the conversation:
Add the server to your AI app — an example for Codex is open below; other apps are collected in collapsible instructions.
Write: "Connect Yandex Direct" — the assistant will walk you through signing in to Yandex and show the account.
For CI and agent setups — a ready-made token and YANDEX_DIRECT_LOGIN, see Connection and configuration.
Through the app interface:
Open Settings → Plugins → MCP servers.
Click Add server.
Add the launch command
npx -y mcp-yandex-direct@latest.
Through the command line:
codex mcp add yandex-direct -- npx -y mcp-yandex-direct@latestCheck the connection:
codex mcp listclaude mcp add --transport stdio --scope user yandex-direct -- npx -y mcp-yandex-direct@latestCheck the connection: claude mcp list.
Open Settings → Developer → Edit Config and add to claude_desktop_config.json:
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"]
}
}
}If there is no Developer section, open the file manually: macOS — ~/Library/Application Support/Claude/claude_desktop_config.json, Windows — %APPDATA%\Claude\claude_desktop_config.json. Restart Claude Desktop.
Open ~/.cursor/mcp.json to connect the server in all projects, or .cursor/mcp.json in a specific project. Add:
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"]
}
}
}In the command palette, run MCP: Open User Configuration. In the opened mcp.json, add the server:
{
"servers": {
"yandex-direct": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"]
}
}
}After saving, run MCP: List Servers and start the server from the list.
What you can delegate
Check how the budget is being spent
"Which campaigns spent the most last week?"
"Which ads are getting impressions and clicks but no conversions?"
"Compare spend, CTR, and average CPC across campaigns for the month."
"Show the account balance and the remaining daily API quota."
Find areas for improvement
"Which keywords are spending budget but getting no clicks?"
"Which ad groups and ads are currently paused or failing moderation?"
"Check which bid adjustments are active for mobile devices."
"What sitelinks and refinements does this campaign have?"
Prepare changes
"Suggest new bids for high-CTR keywords and show the changes before applying."
"Check whether the campaign has negative keywords for this topic and prepare a list."
"Put together the parameters for a new text campaign for Moscow: budget, ad groups, keywords, and ads."
Perform an explicit action
"Add these keywords to group 123 and set the bid to 45 ₽."
"Pause ad 456."
"Upload the page with the image to the ad library."
How it works
Advertising is usually built from three levels: campaign → ad group → ad. The ad group contains keywords, serving settings, and bid adjustments. Ads can have sitelinks, refinements, business cards, and images.
The server helps you look at these objects together: link campaign spend with ad group statistics, keywords, and ads. It can create new campaigns and ads of the text type only. Campaigns of other types can be read, renamed, have their budgets changed, be paused, archived, and deleted by ID.
Statistics are not generated instantly: get_statistics launches a report in the Reports service and waits for it to be ready. Large lists are paginated automatically by autoPaginate.
What can change data
The remote server by URL only reads data. The local server via npx can change a live advertising account:
Action | What happens | What to watch out for |
Read statistics and objects | The server retrieves campaigns, ads, keywords, balance, and reports. | These calls do not change data or move money. |
Create | You can create a text campaign, ad group, text ad, keywords, extensions, or upload an image. | New objects will go into the live account unless the sandbox is enabled. |
Update | You can change budgets, bids, names, negative keywords, ad group settings, and bid adjustments. | Changing bids and budgets can affect spending. |
Change status or delete | You can pause, resume, archive, or delete some objects. | Deletion and some actions are irreversible. |
Direct API request |
| Any method other than reading requires |
The tools pass read, write, and potentially irreversible action labels to the AI app. The app may show a confirmation, but its behavior depends on the client. A direct API request will additionally not perform a write without confirmWrite=true; changing ads requires an explicit request.
Connection and configuration
For normal use, no token is needed in advance:
Ask in the chat to connect Yandex Direct.
Open the Yandex OAuth link under the account with access to the desired advertising account.
Confirm access and send the displayed code back in the chat. That's it — you can work with ads: no need to restart the client or edit the configuration.
From then on, the connection lives on its own: access is renewed automatically and does not expire after a year. To check the status, ask "show connection status"; to disconnect, say "disconnect Direct". The granted access can be revoked in Yandex ID.
For CI and automated setups where there is no conversation, configuration via environment variables is available:
Variable | Purpose |
| Ready-made OAuth token; takes priority over in-chat sign-in. |
| Client login when working through an agency account; otherwise the API will show the agency account. |
|
|
| Client ID of your own OAuth app instead of the built-in one. |
| API response language; defaults to |
| Request timeout; defaults to 60,000 ms. |
| Number of retries on transient errors; defaults to 3. |
You can get a ready-made token for YANDEX_DIRECT_TOKEN via the link, signing in under the account with access to the desired account:
Do not publish the token in chats, repositories, or screenshots: it grants access to the advertising account, including actions that may affect the budget.
Data and telemetry
By default, the server sends anonymous technical events: a random installation identifier, the name of the invoked tool, server versions, AI application, Node.js, and operating system. This is needed to understand which parts of the server are used and whether problems occur at startup. The Yandex token, advertising account data, tool arguments, request texts, values, and names of environment variables are not sent.
To disable telemetry for Ask Ads MCP servers, set the environment variable:
ASKADS_TELEMETRY=0Limitations
Daily API quota. Each call consumes Units. The
get_quotatool shows how much has been spent, how much remains, and what is available for today.Report limits. Yandex reports have their own limits on volume and quantity per day, and report readiness in the Reports service requires waiting.
Large lists. If the internal limit is reached during automatic pagination, the server explicitly marks the result as incomplete rather than hiding this fact.
Temporary errors. The server makes up to three retries under rate limits. Network and server errors are automatically retried only for read operations, so as not to duplicate a change.
Production account. Local changes are applied to the real advertising account and may affect spending. For tests, use the sandbox (
YANDEX_DIRECT_SANDBOX=true).No continuous monitoring. The server runs during a call from the AI application. If the application supports scheduled tasks, you can set up a periodic request to check the needed metrics.
Technical documentation
MCP capabilities catalog — pages on user tasks for each tool.
All tools — parameters, responses, and boundaries of each tool.
Development — project structure and working with the source code.
Yandex Direct API — the primary source on the API and its limitations.
npm package — published server versions.
Support
Found a bug or missing a scenario? Create an issue or write to Telegram.
Available Tools
46 toolsad_actionДействие с объявлениямиADestructive
Выполняет действие над объявлениями по id: moderate, suspend, resume, archive, unarchive или delete.
Inputs: ids (required), action (required), client_login.
add_bid_modifierДобавить корректировку ставокA
Добавляет корректировку ставок на кампанию или группу объявлений. Значения BidModifier — проценты по правилам API (например, 0–1300), а не деньги. API принимает в одном элементе BidModifiers только один тип корректировки, поэтому каждый переданный тип (mobile, desktop, demographics, retargeting, regional) уходит отдельным элементом в одном вызове bidmodifiers/add, в этом порядке. Каждая запись AddResults помечена полем Type (MOBILE_ADJUSTMENT, DESKTOP_ADJUSTMENT, DEMOGRAPHICS_ADJUSTMENT, RETARGETING_ADJUSTMENT, REGIONAL_ADJUSTMENT): типы создаются независимо, при частичной ошибке повторять только типы с Errors. Внутри одного типа (массивы demographics/retargeting/regional) API создаёт всё или ничего.
Inputs: mobile, desktop, regional, adGroupId, +4 more.
add_calloutsДобавить уточненияA
Создаёт уточнения, до 25 символов каждое, не более 1000 за вызов. Уточнения неизменяемы — чтобы поменять, нужно удалить и создать заново. Привязка к объявлениям — через сервис Ads.
Inputs: texts (required), client_login.
add_keywordsДобавить ключевые фразыB
Добавляет ключевые фразы в группу объявлений, при необходимости — со ставками для поиска и сетей.
Inputs: keywords (required), adGroupId (required), client_login.
auth_statusСтатус подключения к ДиректуARead-onlyIdempotent
Показывает, подключён ли Яндекс Директ: есть ли токен, откуда он взят (переменная окружения YANDEX_DIRECT_TOKEN или сохранённый вход), когда истекает и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть и не показывает сам токен. Вызовите это, если инструменты Директа отвечают, что подключение не настроено.
Inputs: no named parameters.
campaign_actionДействие с кампаниямиBDestructive
Выполняет действие над кампаниями по id: suspend, resume, archive, unarchive или delete. Запрос идёт в API v501, в песочнице — в v5.
Inputs: ids (required), action (required), client_login.
clients_overviewСводка по клиентамARead-onlyIdempotent
Сводка по всем клиентам агентства и кабинетам в управлении за один вызов — для вопросов вроде «что у меня по аккаунтам в управлении»: по каждому клиенту баланс общего счёта и число кампаний по состояниям (on — идут или могут идти, suspended — остановлены пользователем, off — не идут по другой причине, ended) и статусам модерации (moderation, rejected, draft). Архивные кампании не считаются. Клиенты — из list_clients, либо явный список logins. Ошибка по одному клиенту (нет доступа, нет общего счёта) не прерывает остальных и попадает в его строку. С параметром stats добавляет показы, клики и расход (с НДС, в валюте клиента) за период — по одному отчёту Reports на клиента, строго по очереди: Яндекс пускает примерно один отчёт в 10 секунд, так что 30 клиентов — около 5 минут; клиенты без неархивных кампаний не запрашиваются, а кто не уложился в 5 минут, помечается statsSkipped. Без stats ответ приходит за секунды — запрашивать расход, только когда вопрос про деньги или трафик. Не вызывать list_campaigns по каждому клиенту в цикле — эта сводка дешевле. Тратит баллы API каждого клиента: один запрос кампаний на клиента и один запрос баланса на 50 клиентов у агентства (у обычного аккаунта — на каждого). Кампании клиентов читаются через API v501, в песочнице — через v5.
Inputs: limit, stats, logins, search.
create_ad_groupСоздать группу объявленийB
Создаёт группу объявлений в кампании с заданными регионами показа. Запрос идёт в API v501, в песочнице — в v5.
Inputs: name (required), regionIds (required), campaignId (required), client_login.
create_sitelinks_setСоздать набор быстрых ссылокA
Создаёт набор быстрых ссылок (1–8 штук). Лимиты API: текст ссылки до 30 символов, описание до 60, URL до 1024 (с протоколом и доменом); длиннее API отвечает «Превышена допустимая длина», поэтому сокращать заранее. Наборы неизменяемы — чтобы поменять ссылки, нужно создать новый набор и переназначить его объявлению.
Inputs: sitelinks (required), client_login.
create_text_adСоздать текстовое объявлениеA
Создаёт текстовое объявление (TextAd) в группе объявлений. Новые объявления создаются черновиками. TextAdAdd требует хотя бы одно из Href/TurboPageId/BusinessId — этот инструмент передаёт посадочную страницу через href (обязателен); объявление с BusinessId вместо ссылки создаётся через raw_request. Визитки (VCardId) Директ больше не поддерживает: контакты задаются организацией из Яндекс Бизнеса (BusinessId). Директ создаёт такие объявления комбинаторными (тип RESPONSIVE_AD), а Title2 объединяет с Title через «. », если вместе они короче 56 символов, иначе отбрасывает; о таких изменениях API сообщает предупреждениями.
Inputs: href (required), text (required), title (required), adGroupId (required), +3 more.
create_text_campaignСоздать текстовую кампаниюA
Создаёт кампанию TextCampaign (текстово-графические объявления). Без biddingStrategy применяются ручные ставки на поиске с отключёнными сетями (Search HIGHEST_POSITION, Network SERVING_OFF) — у ручных ставок текстовой кампании бюджета в API нет. Чтобы ограничить расход, включить автостратегию или сети, передать biddingStrategy целиком — {Search, Network}, недельный бюджет внутри него (WeeklySpendLimit в структуре параметров автостратегии). Дневного бюджета у Директа больше нет. Запрос идёт в API v501, в песочнице — в v5.
Inputs: name (required), startDate (required), endDate, client_login, +4 more.
delete_ad_groupsУдалить группы объявленийADestructive
Удаляет группы объявлений по id (adgroups/delete). Вместе с группой удаляются её объявления и ключевые фразы; отменить это нельзя. Запрос идёт в API v501, в песочнице — в v5.
Inputs: ids (required), client_login.
delete_bid_modifiersУдалить корректировки ставокCDestructive
Удаляет корректировки ставок по id (bidmodifiers/delete).
Inputs: ids (required), client_login.
delete_calloutsУдалить уточненияCDestructive
Удаляет уточнения по id (adextensions/delete).
Inputs: ids (required), client_login.
delete_sitelinksУдалить наборы быстрых ссылокADestructive
Удаляет наборы быстрых ссылок по id (удалить можно только наборы, не привязанные ни к одному объявлению).
Inputs: ids (required), client_login.
finish_loginЗавершить подключение ДиректаAIdempotent
Второй шаг подключения: обменивает код подтверждения из start_login на токен доступа, сохраняет его в файл только для владельца (0600) и сразу проверяет живым запросом к Директу. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Код одноразовый и живёт 10 минут: если он не принят, вызовите start_login заново и попросите свежий.
Inputs: code (required).
get_account_infoДанные аккаунтаBRead-onlyIdempotent
Возвращает данные текущего аккаунта рекламодателя (логин, валюта, тип, страна) через сервис clients Яндекс Директа.
Inputs: fieldNames, client_login.
get_ad_imagesИзображения объявленийARead-onlyIdempotent
Возвращает список изображений из библиотеки изображений, ключ — хеш изображения. Новые изображения загружает upload_ad_image.
Inputs: limit, hashes, offset, client_login.
get_ad_videosВидео объявленийARead-onlyIdempotent
Читает видео из библиотеки видео по id (API требует id). Загрузка идёт через raw_request (advideos/add).
Inputs: ids (required), limit, offset, client_login.
get_balanceБаланс аккаунтаARead-onlyIdempotent
Возвращает баланс общего счёта и финансовые поля (Amount, AmountAvailableForTransfer, Currency, Discount, AccountID) через устаревший сервис AccountManagement Live v4 — единственный API Яндекс Директа, который отдаёт баланс (в v5 финансового метода нет). Amount — строка в ВАЛЮТЕ АККАУНТА (не в микроединицах); отрицательный Amount означает задолженность. По умолчанию — собственный аккаунт токена, а при переданном client_login — счёт этого клиента; чтобы получить несколько общих счетов разом (агентство, до 50 логинов), передать logins.
Inputs: logins, client_login.
get_bid_modifiersКорректировки ставокARead-onlyIdempotent
Читает корректировки ставок (мобильные, десктоп, демография, ретаргетинг, регионы, видео) для кампаний или групп объявлений. BidModifier — это процент, а не деньги.
Inputs: ids, types, levels, adGroupIds, +2 more.
get_calloutsУточненияBRead-onlyIdempotent
Возвращает список уточнений из библиотеки adextensions. Привязать уточнение к объявлению можно через сервис Ads.
Inputs: ids, limit, offset, client_login.
get_creativesКреативыBRead-onlyIdempotent
Возвращает список креативов (смарт-баннеры, HTML5) из библиотеки креативов.
Inputs: ids, limit, offset, client_login.
get_dictionariesСправочникиARead-onlyIdempotent
Возвращает справочники Яндекс Директа (валюты, часовые пояса, константы, категории объявлений, …). GeoRegions может быть очень большим — для поиска регионов лучше get_regions.
Inputs: names (required), client_login.
get_quotaКвота APIARead-onlyIdempotent
Возвращает сегодняшнюю квоту баллов API (потрачено / осталось / лимит) из заголовка Units — чтобы не упереться в дневной лимит.
Inputs: client_login.
get_regionsПоиск регионовARead-onlyIdempotent
Ищет id регионов для таргетинга (те самые regionIds, которые нужны create_ad_group). Фильтр — подстрока названия; количество результатов ограничено limit.
Inputs: limit, query, client_login.
get_sitelinksНаборы быстрых ссылокBRead-onlyIdempotent
Читает наборы быстрых ссылок по id. API требует id наборов — их можно взять из поля SitelinkSetId объявлений.
Inputs: ids (required), limit, offset, client_login.
get_statisticsСтатистикаARead-onlyIdempotent
Запрашивает отчёт по эффективности через сервис Reports Яндекс Директа. По умолчанию отчёт АГРЕГИРОВАН за весь период (одна строка на объект) — добавлять "Date" в fieldNames только для динамики по дням или вопросов о трендах. Почасовой статистики в Reports нет: минимум — сутки, внутридневную динамику дают только повторные снимки TODAY. Готового ROAS нет — считать Revenue / Cost; GoalsRoi — это ROI ((Revenue − Cost) / Cost), не ROAS. Revenue, Profit, GoalsRoi и конверсии заполняются только по целям Метрики с ценностью. ALL_TIME без фильтра по кампаниям отклоняется для отчётов SEARCH_QUERY/CRITERIA: нужно передать campaignIds или ограниченный период. SEARCH_QUERY_PERFORMANCE_REPORT возвращает не сырые строки, а ВЫЧИСЛЕННУЮ СВОДКУ (итоги по ВСЕМ строкам + детализация top-N + свёртка хвоста + количество строк без кликов и без конверсий); её форму задают sortBy/topN/minCost/queryContains/zeroClicksOnly/zeroConversionsOnly, а для подсчётов по конверсиям нужно добавить Conversions в fieldNames. Остальные типы отчётов возвращают строки, разделённые табуляцией (без заголовка). compareTo — сравнение двух периодов: инструмент запускает ДВЕ задачи Reports (текущий период dateFrom/dateTo и compareTo) и возвращает JSON, где строки сопоставлены по разрезам отчёта (matchKey; название кампании или группы не учитывается, если запрошен её id — переименование не ломает сопоставление), с current, previous, delta и deltaPct по каждой метрике. Это только значения Яндекса и их разность: вклад факторов (расход = показы × CTR × CPC) инструмент не считает — при объяснении изменений считать по колонкам ответа и называть порядок факторов. Последние ~3 дня статистики Яндекс может пересчитать.
Inputs: topN, goals, order, dateTo, +15 more.
keyword_actionДействие с ключевыми фразамиCDestructive
Выполняет действие над ключевыми фразами по id: suspend, resume или delete.
Inputs: ids (required), action (required), client_login.
list_ad_groupsСписок групп объявленийARead-onlyIdempotent
Возвращает список групп объявлений. Нужно передать campaignIds и/или ids — API Яндекс Директа требует хотя бы один критерий отбора. Запрос идёт в API v501 (в песочнице — в v5): группы Единой перформанс-кампании приходят с Type UNIFIED_AD_GROUP (v5 называет их TEXT_AD_GROUP; ответ v5 доступен через raw_request с apiVersion "v5").
Inputs: ids, limit, offset, fieldNames, +3 more.
list_adsСписок объявленийARead-onlyIdempotent
Возвращает список объявлений. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них; states и statuses только сужают выборку. Текстовые объявления Единой перформанс-кампании Директ хранит комбинаторными и отдаёт в одном из двух видов. Без responsiveAdFieldNames — в виде совместимости: Type TEXT_AD, запрошенные тексты в объекте TextAd. Если передано хотя бы одно поле в responsiveAdFieldNames — как Type RESPONSIVE_AD с объектом ResponsiveAd вместо TextAd, где заголовки и тексты — массивы Titles[] и Texts[] со статусом модерации каждого варианта.
Inputs: ids, limit, offset, states, +7 more.
list_campaignsСписок кампанийARead-onlyIdempotent
Возвращает список кампаний с необязательными фильтрами по id, типу, состоянию и статусу. Запрос идёт в API v501 (в песочнице — в v5): только он отдаёт Единую перформанс-кампанию с типом UNIFIED_CAMPAIGN (v5 называет её TEXT_CAMPAIGN; ответ v5 доступен через raw_request с apiVersion "v5"). Денежные поля (Funds общего счёта — Sum, Balance, SumAvailableForTransfer, Spend) отдаются в валюте аккаунта. Бюджет кампании — недельный (WeeklySpendLimit) и у ручных ставок, и у автостратегий; он лежит внутри BiddingStrategy и виден только при strategy: true (дневного бюджета DailyBudget у API больше нет). strategy: true добавляет блок TextCampaign/UnifiedCampaign со стратегией (BiddingStrategy), ключевыми целями (PriorityGoals), счётчиками Метрики, моделью атрибуции, пакетной стратегией и переносом бюджета (WeeklyBudgetRollover — сколько добавлено к недельному бюджету за счёт неиспользованного на прошлой неделе, до 30%; null — перенос не применяется или данных нет) — деньги в нём тоже в валюте аккаунта, а сам объект BiddingStrategy в этом виде принимает set_campaign_strategy.
Inputs: ids, limit, types, offset, +6 more.
list_clientsКлиенты и кабинеты в управленииARead-onlyIdempotent
Перечисляет рекламодателей, с которыми может работать токен: клиентов агентства (AgencyClients.get) и кабинеты в управлении из YANDEX_DIRECT_CLIENTS. Логин из ответа передаётся в параметр client_login любого инструмента данных — так один сервер работает со всеми клиентами без перезапуска. accountType=agency — токен агентства: без client_login (и без YANDEX_DIRECT_LOGIN) инструменты видят собственный аккаунт агентства, где обычно нет кампаний. accountType=advertiser — обычный аккаунт: API не перечисляет кабинеты, где этот логин представитель, поэтому список есть только если его задали в YANDEX_DIRECT_CLIENTS. Архивные клиенты агентства по умолчанию скрыты. Сводка по всем клиентам сразу (баланс, кампании) — clients_overview.
Inputs: limit, search, includeArchived.
list_keywordsСписок ключевых фразARead-onlyIdempotent
Возвращает список ключевых фраз. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них. Bid и ContextBid отдаются в валюте аккаунта.
Inputs: ids, limit, offset, adGroupIds, +4 more.
logoutОтключить ДиректADestructive
Удаляет сохранённый токен Директа с диска. Токен, заданный переменной окружения YANDEX_DIRECT_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. Доступ, выданный приложению, остаётся активным на стороне Яндекса: отозвать его можно в Яндекс ID.
Inputs: no named parameters.
raw_requestПрямой вызов API Яндекс ДиректаADestructive
Универсальный запрос: вызывает напрямую любой сервис или метод API Яндекс Директа (например service "bidmodifiers", method "get"). Нужен для сервисов, у которых нет отдельного инструмента. Деньги — в микроединицах (без конвертации). Методы чтения (get/has/check) выполняются свободно; любой другой метод считается записью и требует confirmWrite=true. Версия API по умолчанию — v5, а для сервисов campaigns и adgroups — v501: только она называет Единую перформанс-кампанию и её группы настоящими типами (UNIFIED_CAMPAIGN, UNIFIED_AD_GROUP) и фильтрует по ним, v5 выдаёт их за TEXT_CAMPAIGN и TEXT_AD_GROUP. Параметр apiVersion задаёт версию явно для любого сервиса.
Inputs: method (required), service (required), params, apiVersion, +2 more.
set_bid_modifiersИзменить корректировки ставокAIdempotent
Меняет процент существующих корректировок (bidmodifiers/set) по id корректировки. BidModifierSetItem принимает только Id и BidModifier; включить/выключить корректировку через API нельзя (метод bidmodifiers/toggle устарел и не поддерживается) — чтобы отключить корректировку, удалить её через delete_bid_modifiers.
Inputs: bids (required), client_login.
set_campaign_strategyИзменить стратегию кампанииAIdempotent
Меняет стратегию показа (BiddingStrategy) текстовой кампании или ЕПК. Формат — объект API как есть, в том же виде, в каком его отдаёт list_campaigns с strategy: true, поэтому порядок такой: прочитать текущую стратегию, показать её пользователю, скопировать и поправить нужное поле. Сервер делает только три вещи: (1) одним campaigns.get узнаёт тип кампании и кладёт стратегию в TextCampaign или UnifiedCampaign; (2) переводит деньги из валюты аккаунта в микроединицы — WeeklySpendLimit, BidCeiling, AverageCpc, AverageCpa, Cpa, SpendLimit, MinimumExplorationBudget (Crr и BudgetIncreasePercent — проценты, не деньги); (3) возвращает previous — стратегию до изменения — рядом с UpdateResults. Больше ничего не дописывается и не проверяется: правила совместимости проверяет API и отвечает ошибкой по объекту. Бюджет кампании — недельный и задаётся только здесь: у автостратегий — WeeklySpendLimit в их структуре параметров, у ручных ставок ЕПК — {BiddingStrategyType: HIGHEST_POSITION, HighestPosition: {WeeklySpendLimit}}; у ручных ставок текстовой кампании бюджета нет (API отвечает 8000 на HighestPosition). Дневного бюджета (DailyBudget) у Директа больше нет. Передаются обе стороны, search и network. Внутри структуры параметров непереданные поля той же стратегии сохраняют текущие значения (проверено вживую на ЕПК). PriorityGoals, CounterIds и AttributionModel этим инструментом не меняются (raw_request). Правила API: автостратегия на поиске ⇒ в сетях только NETWORK_DEFAULT или SERVING_OFF; автостратегия в сетях ⇒ на поиске SERVING_OFF. Конверсионные стратегии требуют GoalId цели Метрики и счётчик на кампании; стратегии *_MULTIPLE_GOALS берут цели из PriorityGoals. Минимумы бюджета и ставок — get_dictionaries → Currencies. Смена типа стратегии перезапускает её обучение. Кампании других типов и кампании в пакетной стратегии — через raw_request. Запрос идёт в API v501, в песочнице — в v5.
Inputs: id (required), search (required), network (required), client_login.
set_keyword_bidsЗадать ставки ключевых фразAIdempotent
Задаёт ручные ставки на поиске и в сетях для ключевых фраз либо для всех фраз указанных групп объявлений или кампаний (keywordbids/set). Ставки — в валюте аккаунта. Тип цели один на весь вызов: все элементы bids используют только keywordId, только adGroupId или только campaignId; для целей разных типов нужны отдельные вызовы.
Inputs: bids (required), client_login.
start_loginНачать подключение ДиректаARead-onlyIdempotent
Первый шаг подключения Яндекс Директа без правки конфигурации и без перезапуска клиента. Возвращает ссылку на страницу Яндекс OAuth. Покажите ссылку пользователю целиком и попросите: открыть её в браузере под аккаунтом, у которого есть доступ к нужному рекламному кабинету, подтвердить доступ и прислать показанный код подтверждения. Полученный код передайте в finish_login. Код действует 10 минут. Сам по себе код бесполезен для постороннего: обменять его может только этот сервер.
Inputs: no named parameters.
update_ad_groupОбновить группу объявленийBIdempotent
Обновляет название и/или регионы показа группы объявлений (adgroups/update). Запрос идёт в API v501, в песочнице — в v5.
Inputs: id (required), name, regionIds, client_login, +1 more.
update_campaignОбновить кампаниюAIdempotent
Обновляет название, дату окончания и/или минус-фразы кампании (campaigns/update). Бюджет здесь не меняется: у Директа он недельный и является частью стратегии — set_campaign_strategy (WeeklySpendLimit в структуре параметров автостратегии; у ручных ставок — HighestPosition: {WeeklySpendLimit}, только у ЕПК). Запрос идёт в API v501, в песочнице — в v5.
Inputs: id (required), name, endDate, client_login, +3 more.
update_excluded_sitesИзменить запрещённые площадкиADestructive
Меняет список площадок, где кампании запрещено показываться (ExcludedSites): сайты, мобильные приложения и внешние сети РСЯ. Действует только в сетях, на поиске площадки не запрещаются. API хранит список целиком и при записи заменяет его, поэтому действие задаётся явно:
add — дописать площадки к текущим. Инструмент читает текущий список (campaigns/get) и записывает объединённый (campaigns/update): два вызова API. Уже исключённые не дублируются.
remove — вернуть показы на указанных площадках. Тоже чтение + запись.
replace — записать ровно переданный список вместо текущего, без чтения. Пустой список здесь не принимается — для очистки есть clear.
clear — снять все запреты (отправляется null). Значения: домен без протокола (example.com — API сам уберёт www. и приведёт к нижнему регистру), id приложения Android/iOS в виде com.example.app (числовой id App Store вида id123456789 API отвергает), название внешней сети из get_dictionaries → SupplySidePlatforms (например BidSwitch). Значение площадки из отчёта get_statistics (поле Placement, строки с AdNetworkType=AD_NETWORK) передаётся как есть. Если add/remove ничего не меняют, записи нет (changed: false). Ответ: before/after — число площадок до и после, added/alreadyPresent или removed/notFound. Между чтением и записью нет блокировки: правка того же списка в интерфейсе в эту секунду будет перезаписана. Лимиты API: до 1000 площадок, до 255 символов в каждой. Текущий список — list_campaigns с fieldNames ["ExcludedSites"]. Запрос идёт в API v501, в песочнице — в v5.
Inputs: action (required), campaignId (required), sites, client_login.
update_negative_keywordsИзменить минус-фразыADestructive
Меняет минус-фразы одной кампании или одной группы объявлений. API хранит список целиком и при записи заменяет его, поэтому действие задаётся явно:
add — дописать фразы к текущим. Инструмент читает текущий список (campaigns/get или adgroups/get) и записывает объединённый (update): два вызова API. Уже имеющиеся фразы не дублируются.
remove — убрать указанные фразы из текущего списка. Тоже чтение + запись.
replace — записать ровно переданный список вместо текущего, без чтения. Пустой список здесь не принимается — для очистки есть clear.
clear — удалить все минус-фразы (отправляется null). Фразы сравниваются без учёта регистра и лишних пробелов — так же склеивает их сам API; морфологию и порядок слов инструмент не учитывает. Если add/remove ничего не меняют, записи нет (changed: false). Ответ: before/after — число фраз до и после, added/alreadyPresent или removed/notFound — что именно произошло. Между чтением и записью нет блокировки: правка того же списка в интерфейсе в эту секунду будет перезаписана. Ограничения API: фраза без минуса в начале, до 7 слов, слово до 35 символов; суммарно до 20 000 символов на кампанию и 4096 на группу — нарушения API вернёт ошибкой по объекту. Минус-фразы кампании и группы действуют вместе. Запрос идёт в API v501, в песочнице — в v5.
Inputs: action (required), phrases, adGroupId, campaignId, +1 more.
update_text_adОбновить текстовое объявлениеAIdempotent
Обновляет заголовок, текст или посадочную страницу текстового объявления (ads/update). Правка активного объявления отправляет его на повторную модерацию.
Inputs: id (required), href, text, title, +2 more.
upload_ad_imageЗагрузить изображениеA
Загружает изображение в библиотеку изображений (adimages/add) и возвращает его AdImageHash — этот хеш подставляется в поле AdImageHash текстово-графического объявления. Изображение передаётся публичным URL (сервер сам скачает и закодирует) или в base64 через imageData. Яндекс принимает JPG/PNG/GIF до 10 МБ; текстово-графическому объявлению нужна горизонтальная картинка (минимум 1080×607).
Inputs: name (required), url, imageData, client_login.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 46 tools
The descriptions are very detailed and many tools target distinct resources, but several boundaries are fuzzy: campaign_action vs update_campaign vs set_campaign_strategy, ad_action / keyword_action vs update_text_ad, and read helpers such as get_balance vs get_account_info and list_clients vs clients_overview. raw_request also overlaps every operation as a fallback, which weakens tool selection clarity.
Most names follow a snake_case verb_noun pattern, and the action families campaign_action, ad_action, and keyword_action are consistent. There are some deviations such as clients_overview, auth_status, raw_request, and noun-only get_dictionaries, plus mixed add_/create_/set_/update_ verbs, but the overall convention remains readable.
46 tools is far above the typical well-scoped range of 3-15, even for a broad advertising platform. The server already has raw_request as an escape hatch, so many granular CRUD/read endpoints make the set feel heavy and increase selection cost.
The surface covers campaigns, ad groups, ads, keywords, bid modifiers, sitelinks, callouts, images, statistics, clients, balances, quotas, and authentication. Minor gaps remain around video/creative creation or update and some extension binding operations, but raw_request provides a workable fallback.
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.
Google Ads analysis and operations — read performance, manage keywords, bids, and campaigns.
Yandex Direct, Metrika & Wordstat MCP for Russian digital marketing.
Related MCP Servers
- AlicenseAqualityDmaintenanceIntegrates with Yandex Direct API v5 to manage ads via 20 tools, with dry-run protection preventing accidental spending.21MIT
- 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
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.21MIT
- AlicenseAqualityDmaintenanceEnables AI agents to manage Yandex Direct advertising accounts via the API v5, including reports, bids, campaign management, and semantic analysis through natural language requests.4MIT