yandex-direct-mcp
This server provides tools to manage Yandex.Direct advertising campaigns from any MCP client (e.g., Claude, Cursor), covering campaigns, ad groups, ads, keywords, bids, negative keywords, statistics, and account balance.
Campaign Management
List campaigns with filtering by status and type
Get detailed info about a specific campaign (budget, status, dates, stats)
Create new campaigns (name, type, start date, daily budget)
Update campaigns (name, budget, or status: SUSPEND/RESUME/ARCHIVE/UNARCHIVE)
Ad Group Management
List ad groups for selected campaigns (names, regions, statuses)
Create ad groups within a campaign with regional targeting
Delete ad groups and set negative keywords (minus-phrases)
Ad Management
List ads within ad groups (titles, texts, links, statuses)
Create text ads (headline, body, second headline, URL)
Update ads and manage statuses (pause, archive, moderation, delete)
Keyword Management
List keywords in ad groups (phrases, bids, statuses)
Add keywords to an ad group
Set bids for search and ad networks
Set campaign-level negative keywords
Statistics & Account
Retrieve campaign performance reports for a date range (impressions, clicks, cost, CTR, CPC)
Check account balance
Access the regions directory
Additional Notes
Budgets and bids are in rubles; the server converts to API micro-units automatically
Supports sandbox mode (
YANDEX_DIRECT_SANDBOX=1) for safe testingSupports agency mode via
Client-Loginheader for managing client accounts
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 all 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.
🗄 Repository archived
Development has moved to theYahia/YaAll — a build where the entire Yandex layer lives in one place: official Yandex MCP servers, MCP for Direct and Metrika, the YaGEO skill, and the Wordstat gate.
The current version of what was here:
mcp/yandex-direct-mcp/Nothing is updated here anymore. Issues and pull requests — in YaAll.
Archived — development moved to theYahia/YaAll, a single repository bundling the whole Yandex stack. The current version of this package now lives at
mcp/yandex-direct-mcp/. Please open issues and pull requests there.
@theyahia/yandex-direct-mcp
MCP server for the Yandex.Direct API — manage contextual advertising from any MCP client (Claude, Cursor, etc.): campaigns, ad groups, ads, keywords, bids, negative keywords, statistics, balance. 20 tools.
Money is in rubles (budgets, bids on input and output); the server itself converts to API micro-units. Sandbox for safe testing and agency mode (Client-Login) are supported.
Related MCP server: yandex-mcp
Installation
Claude Desktop
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "@theyahia/yandex-direct-mcp"],
"env": {
"YANDEX_DIRECT_TOKEN": "ваш_токен"
}
}
}
}Claude Code
claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y @theyahia/yandex-direct-mcpConfiguration (environment variables)
Variable | Required | Purpose |
| yes | Yandex.Direct OAuth token |
| no |
|
| no | Client login for agency tokens ( |
How to get a token
The OAuth token is issued for an app registered in Yandex OAuth with access to the Direct API. Details — app registration and getting a token. API access must be requested in the Direct interface.
⚠️ Warning: real spending
The create_campaign, create_text_ad, add_keywords, set_keyword_bids and other tools modify a live advertising account and can spend money. For debugging scenarios, enable the sandbox (YANDEX_DIRECT_SANDBOX=1).
Tools (20)
Campaigns
Tool | Description |
| List of campaigns (filter by status/type, pagination) |
| Detailed campaign info by ID |
| Create a campaign (budget in rubles, strategy selection) |
| Update name/budget and/or status (SUSPEND/RESUME/ARCHIVE/UNARCHIVE) |
Ad groups
Tool | Description |
| Ad groups of selected campaigns |
| Create a group with region targeting |
| Delete groups by ID |
| Set group negative keywords |
Ads
Tool | Description |
| Ads in groups |
| Create a text ad (≤56/≤30/≤81) |
| Update headline/text/link |
| suspend/resume/archive/unarchive/moderate/delete |
Keywords and bids
Tool | Description |
| Keyword phrases in groups (bids in rubles) |
| Add keyword phrases |
| Set bids (search/network, rubles) on phrases/groups/campaigns |
| suspend/resume/delete |
| Set campaign negative keywords |
Statistics, account, reference data
Tool | Description |
| Statistics for a period (impressions, clicks, spend, CTR, CPC) |
| Account balance (Live API v4) |
| Region code reference (225 = Russia) |
Example requests
Покажи все активные рекламные кампании
Создай кампанию "Летняя распродажа" с бюджетом 5000 ₽/день, старт 2026-05-01
Установи ставку 25 ₽ на ключевые фразы 111 и 222
Добавь минус-фразы "бесплатно", "скачать" в кампанию 12345
Какая статистика у кампаний 12345 и 67890 за последнюю неделю?
Найди код региона для Новосибирска
Покажи баланс аккаунтаDevelopment
npm install
npm run build # tsc → dist/
npm test # vitest (моки fetch)
npm run dev # tsx src/index.tsLicense
MIT
Available Tools
20 toolsadd_keywordsДобавить ключевые словаB
Добавить ключевые фразы в группу объявлений.
Inputs: ad_group_id (required), keywords (required).
create_ad_groupСоздать группуB
Создать группу объявлений в кампании с таргетингом по регионам (см. get_regions).
Inputs: campaign_id (required), name (required), region_ids (required).
create_campaignСоздать кампаниюA
Создать новую рекламную кампанию. Бюджет в рублях. ⚠️ Тратит реальные деньги — используйте sandbox для теста.
Inputs: name (required), start_date (required), type, daily_budget, +2 more.
create_text_adСоздать объявлениеB
Создать текстовое объявление: заголовок (≤56), второй заголовок (≤30), текст (≤81), ссылка.
Inputs: ad_group_id (required), title (required), text (required), href (required), +1 more.
delete_ad_groupsУдалить группыADestructive
Удалить группы объявлений по их ID. ⚠️ Необратимо.
Inputs: ad_group_ids (required).
get_account_balanceБаланс аккаунтаBRead-only
Баланс и финансовая информация аккаунта (Amount, Currency) через Live API v4.
Inputs: logins.
get_campaignКампания по IDARead-only
Детальная информация о кампании по ID: бюджет (руб), статус, даты, статистика.
Inputs: campaign_id (required).
get_regionsСправочник регионовARead-only
Справочник кодов регионов (GeoRegions) для таргетинга. Фильтр по названию. 225 = Россия.
Inputs: search, limit.
get_statisticsСтатистикаARead-only
Статистика кампаний за период: показы, клики, расход (руб), CTR, CPC (ReportService, TSV).
Inputs: campaign_ids (required), date_from (required), date_to (required), fields.
list_ad_groupsСписок группBRead-only
Группы объявлений выбранных кампаний: названия, регионы, статусы.
Inputs: campaign_ids (required), limit, offset.
list_adsСписок объявленийBRead-only
Объявления в группах: заголовки, тексты, ссылки, статусы.
Inputs: ad_group_ids (required), limit, offset.
list_campaignsСписок кампанийARead-only
Список рекламных кампаний Яндекс.Директ с фильтрацией по статусу и типу. Бюджеты — в рублях.
Inputs: status, types, limit, offset.
list_keywordsСписок ключевых словBRead-only
Ключевые фразы в группах объявлений: фразы, ставки (руб), статусы.
Inputs: ad_group_ids (required), limit, offset.
manage_adsУправление объявлениямиADestructive
Действие над объявлениями: suspend/resume/archive/unarchive/moderate/delete. ⚠️ delete необратимо.
Inputs: ad_ids (required), action (required).
manage_keywordsУправление ключевыми словамиADestructive
Действие над ключевыми фразами: suspend/resume/delete. ⚠️ delete необратимо.
Inputs: keyword_ids (required), action (required).
set_ad_group_negative_keywordsМинус-фразы группыAIdempotent
Задать минус-фразы на уровне группы объявлений (заменяет текущий список; пустой массив очищает).
Inputs: ad_group_id (required), negative_keywords (required).
set_campaign_negative_keywordsМинус-фразы кампанииAIdempotent
Задать минус-фразы на уровне кампании (заменяет текущий список; пустой массив очищает).
Inputs: campaign_id (required), negative_keywords (required).
set_keyword_bidsУстановить ставкиAIdempotent
Установить ставки (поиск/сети, в рублях) на уровне фраз, групп или кампаний (сервис Bids).
Inputs: keyword_ids, ad_group_ids, campaign_ids, bid, +1 more.
update_campaignОбновить кампаниюAIdempotent
Обновить кампанию: название, бюджет (руб) и/или статус (SUSPEND/RESUME/ARCHIVE/UNARCHIVE).
Inputs: campaign_id (required), name, daily_budget, status.
update_text_adОбновить объявлениеAIdempotent
Обновить текстовое объявление: заголовок, текст, ссылка. Изменённое объявление уходит на модерацию.
Inputs: ad_id (required), title, title2, text, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a distinct action and level (campaign, ad group, ad, keyword, etc.). There is no overlap in purpose; even similar tools like `add_keywords` and `set_keyword_bids` handle different aspects (adding phrases vs setting bids).
All tool names use a consistent verb_noun snake_case pattern (e.g., `create_campaign`, `list_ads`, `set_keyword_bids`). Verbs like create, get, list, update, delete, manage, set, add are used consistently across similar operations.
20 tools is appropriate for a Yandex Direct advertising platform. It covers account management, campaign/ad group/ad operations, keywords, negative keywords, bids, stats, and reference data without being excessive or too sparse.
Core workflows are covered, but notable gaps exist: no campaign delete, no update for ad groups, and no individual get tools for ad groups or keywords (only list). Missing management for ad types beyond text ads. These gaps may hinder some use cases.
Maintenance
Related MCP Connectors
Google Ads MCP server — manage campaigns, keywords, and metrics.
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
Yandex Direct, Metrika & Wordstat MCP for Russian digital marketing.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server for managing Yandex Direct advertising, Yandex Metrica analytics, Wordstat keyword research, and Yandex Webmaster SEO tools, with self-configuring OAuth; provides 153 tools for complete ad and search workflows from AI assistants.10012 npm3MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Yandex Direct, Metrika, Wordstat, and Webmaster APIs, providing 132 tools to manage advertising campaigns, analytics, keyword research, and reporting through any MCP-compatible client.58MIT
- 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
- AlicenseNot gradedqualityCmaintenanceMCP server for Yandex Direct, Yandex Metrika, and Wordstat with 120 tools to manage contextual advertising from AI assistants.MIT