Skip to main content
Glama
yandex-direct-mcp

yandex-direct-mcp

by theYahia

🗄 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.

npm License: MIT

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-mcp

Configuration (environment variables)

Variable

Required

Purpose

YANDEX_DIRECT_TOKEN

yes

Yandex.Direct OAuth token

YANDEX_DIRECT_SANDBOX

no

1 — work in the sandbox (isolated data, no spending). Same token, only the URL differs

YANDEX_DIRECT_LOGIN

no

Client login for agency tokens (Client-Login header). Required if the token is an agency one

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_campaigns

List of campaigns (filter by status/type, pagination)

get_campaign

Detailed campaign info by ID

create_campaign

Create a campaign (budget in rubles, strategy selection)

update_campaign

Update name/budget and/or status (SUSPEND/RESUME/ARCHIVE/UNARCHIVE)

Ad groups

Tool

Description

list_ad_groups

Ad groups of selected campaigns

create_ad_group

Create a group with region targeting

delete_ad_groups

Delete groups by ID

set_ad_group_negative_keywords

Set group negative keywords

Ads

Tool

Description

list_ads

Ads in groups

create_text_ad

Create a text ad (≤56/≤30/≤81)

update_text_ad

Update headline/text/link

manage_ads

suspend/resume/archive/unarchive/moderate/delete

Keywords and bids

Tool

Description

list_keywords

Keyword phrases in groups (bids in rubles)

add_keywords

Add keyword phrases

set_keyword_bids

Set bids (search/network, rubles) on phrases/groups/campaigns

manage_keywords

suspend/resume/delete

set_campaign_negative_keywords

Set campaign negative keywords

Statistics, account, reference data

Tool

Description

get_statistics

Statistics for a period (impressions, clicks, spend, CTR, CPC)

get_account_balance

Account balance (Live API v4)

get_regions

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.ts

License

MIT

Available Tools

20 tools
add_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Удалить группыA
Destructive

Удалить группы объявлений по их ID. ⚠️ Необратимо.

Inputs: ad_group_ids (required).

get_account_balanceБаланс аккаунтаB
Read-only

Баланс и финансовая информация аккаунта (Amount, Currency) через Live API v4.

Inputs: logins.

get_campaignКампания по IDA
Read-only

Детальная информация о кампании по ID: бюджет (руб), статус, даты, статистика.

Inputs: campaign_id (required).

get_regionsСправочник регионовA
Read-only

Справочник кодов регионов (GeoRegions) для таргетинга. Фильтр по названию. 225 = Россия.

Inputs: search, limit.

get_statisticsСтатистикаA
Read-only

Статистика кампаний за период: показы, клики, расход (руб), CTR, CPC (ReportService, TSV).

Inputs: campaign_ids (required), date_from (required), date_to (required), fields.

list_ad_groupsСписок группB
Read-only

Группы объявлений выбранных кампаний: названия, регионы, статусы.

Inputs: campaign_ids (required), limit, offset.

list_adsСписок объявленийB
Read-only

Объявления в группах: заголовки, тексты, ссылки, статусы.

Inputs: ad_group_ids (required), limit, offset.

list_campaignsСписок кампанийA
Read-only

Список рекламных кампаний Яндекс.Директ с фильтрацией по статусу и типу. Бюджеты — в рублях.

Inputs: status, types, limit, offset.

list_keywordsСписок ключевых словB
Read-only

Ключевые фразы в группах объявлений: фразы, ставки (руб), статусы.

Inputs: ad_group_ids (required), limit, offset.

manage_adsУправление объявлениямиA
Destructive

Действие над объявлениями: suspend/resume/archive/unarchive/moderate/delete. ⚠️ delete необратимо.

Inputs: ad_ids (required), action (required).

manage_keywordsУправление ключевыми словамиA
Destructive

Действие над ключевыми фразами: suspend/resume/delete. ⚠️ delete необратимо.

Inputs: keyword_ids (required), action (required).

set_ad_group_negative_keywordsМинус-фразы группыA
Idempotent

Задать минус-фразы на уровне группы объявлений (заменяет текущий список; пустой массив очищает).

Inputs: ad_group_id (required), negative_keywords (required).

set_campaign_negative_keywordsМинус-фразы кампанииA
Idempotent

Задать минус-фразы на уровне кампании (заменяет текущий список; пустой массив очищает).

Inputs: campaign_id (required), negative_keywords (required).

set_keyword_bidsУстановить ставкиA
Idempotent

Установить ставки (поиск/сети, в рублях) на уровне фраз, групп или кампаний (сервис Bids).

Inputs: keyword_ids, ad_group_ids, campaign_ids, bid, +1 more.

update_campaignОбновить кампаниюA
Idempotent

Обновить кампанию: название, бюджет (руб) и/или статус (SUSPEND/RESUME/ARCHIVE/UNARCHIVE).

Inputs: campaign_id (required), name, daily_budget, status.

update_text_adОбновить объявлениеA
Idempotent

Обновить текстовое объявление: заголовок, текст, ссылка. Изменённое объявление уходит на модерацию.

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

    A3.8/5.0

    Scored across 20 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP 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.
      100
      12 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      58
      MIT