How do I use yandex-direct-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@yandex-direct-mcp Show campaign performance for last 30 days" 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

by nikolaymokh-dev

Overview Schema Source Related Servers Discussions Admin

Python

Local

yandex-direct-mcp

Hardened форк axisrow/yandex-direct-mcp-plugin. Управление Яндекс.Директом из MCP-клиента (Claude Code, Cursor и другие). Только чтение по умолчанию — запись включается явно через YANDEX_DIRECT_ENABLE_WRITES=true. OAuth реализован пакетом direct-cli (бинарь direct); каждый пользователь авторизуется под своим Яндекс-аккаунтом.

Профили и поверхность инструментов

Профиль	Как активируется	Что включено	Инструментов
analytics (по умолчанию)	—	Отчёты, статистика, прогноз, Wordstat, словари, изменения (только чтение)	~26
campaign-editor	`YANDEX_DIRECT_ENABLE_WRITES=true`	Управление кампаниями, группами, объявлениями, ставками (чтение + запись)	~36
Финансы	`YANDEX_DIRECT_ENABLE_FINANCE=true` вместе с writes	Пополнение счёта, счета, переводы (`v4account_deposit` / `invoice` / `transfer_money`)	+3
full	`YANDEX_DIRECT_TOOL_PROFILE=full`	Все 146 инструментов	146

Переменные окружения

Переменная	Назначение
`YANDEX_DIRECT_ENABLE_WRITES`	`true` → активирует профиль `campaign-editor`. По умолчанию не установлена (только чтение).
`YANDEX_DIRECT_ENABLE_FINANCE`	`true` → включает финансовые инструменты. Работает только вместе с `ENABLE_WRITES`; на профиле `analytics` не даёт эффекта.
`YANDEX_DIRECT_TOOL_PROFILE`	Явный выбор профиля: `analytics` \| `core` \| `campaign-editor` \| `full`. Переопределяет логику ENABLE_WRITES.
`YANDEX_DIRECT_ENABLED_GROUPS`	Allow-list групп (через запятую): `campaigns`, `ads`, `read`, `mutate`, `analytics`, …
`YANDEX_DIRECT_DISABLED_GROUPS`	Убрать группы из активной поверхности (не расширяет до full — safe-by-default).
`YANDEX_DIRECT_ENABLED_TOOLS`	Allow-list конкретных инструментов (через запятую).
`YANDEX_DIRECT_DISABLED_TOOLS`	Убрать конкретные инструменты из активной поверхности.

Важно: DISABLED_* переменные уточняют активную поверхность, но не расширяют её до полного набора. Если одновременно не указаны ENABLED_*, не выставлен явный TOOL_PROFILE и не установлен ENABLE_WRITES=true — сервер стартует в профиле analytics (только чтение).

Приоритет: YANDEX_DIRECT_ENABLE_WRITES игнорируется, если задан YANDEX_DIRECT_TOOL_PROFILE или любая из YANDEX_DIRECT_ENABLED_GROUPS/YANDEX_DIRECT_ENABLED_TOOLS — явный профиль или allow-list имеют приоритет.

Related MCP server: yandex-marketing-mcp

Установка

Claude Code (рекомендуемый способ — uvx)

claude mcp add yandex-direct \
  -- uvx --from git+https://github.com/nikolaymokh-dev/yandex-direct-mcp@v0.1.0 yandex-direct-mcp

Чтобы включить запись:

claude mcp add yandex-direct \
  --env YANDEX_DIRECT_ENABLE_WRITES=true \
  -- uvx --from git+https://github.com/nikolaymokh-dev/yandex-direct-mcp@v0.1.0 yandex-direct-mcp

`.claude.json` / Cursor / другие MCP-клиенты

{
  "mcpServers": {
    "yandex-direct": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nikolaymokh-dev/yandex-direct-mcp@v0.1.0",
        "yandex-direct-mcp"
      ],
      "env": {
        "YANDEX_DIRECT_ENABLE_WRITES": "true"
      }
    }
  }
}

Поле "env" не обязательно — без него сервер запускается в read-only (analytics) режиме.

Запуск standalone (без MCP-клиента, для проверки)

uvx --from git+https://github.com/nikolaymokh-dev/yandex-direct-mcp@v0.1.0 yandex-direct-mcp

Запускает stdio-сервер напрямую (для теста установки; обычно сервер запускает MCP-клиент).

Первый вход (OAuth / PKCE)

После установки и запуска MCP-сервера вызовите инструмент auth_login:

mcp__yandex_direct__auth_login()

Сервер напечатает URL. Откройте его в браузере и авторизуйтесь в своём Яндекс-аккаунте. PKCE-поток реализован пакетом direct-cli; токен сохраняется локально в ~/.direct-cli/auth.json (права 0600).

Не используйте auth_setup(code=...) на общих машинах — код авторизации будет виден в ps и системных логах.

Включение управления кампаниями и финансов

Запись (управление кампаниями, группами, объявлениями, ставками):

# В ~/.claude/settings.json
{
  "env": {
    "YANDEX_DIRECT_ENABLE_WRITES": "true"
  }
}

Финансовые инструменты (пополнение, счета, переводы) — отдельное осознанное решение:

{
  "env": {
    "YANDEX_DIRECT_ENABLE_WRITES": "true",
    "YANDEX_DIRECT_ENABLE_FINANCE": "true"
  }
}

⚠ Финансовые операции работают с реальными деньгами. Включайте только в окружениях с явными правами на финансовые транзакции.

(Опционально) Запуск как Claude Code плагин

Если репозиторий клонирован локально, плагин запускается через hooks/run-server.sh:

// .mcp.json (пример для Claude Code plugin channel)
{
  "mcpServers": {
    "yandex-direct-mcp": {
      "command": "bash",
      "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run-server.sh"]
    }
  }
}

Детали bootstrap и troubleshooting — в hooks/setup.sh и CLAUDE.md.

Документация

Настройка доступа к API → docs/SETUP.md
Модель угроз и безопасность → docs/SECURITY.md
Синхронизация с upstream → docs/SYNC.md

Лицензия

MIT — форк axisrow/yandex-direct-mcp-plugin, см. NOTICE.

Available Tools

26 tools

auth_loginA

Start interactive OAuth login through direct (elicits the authorization code); use auth_setup if you already have a y0_ token. Call tool_help('auth_login') for parameters.

Inputs: login, profile, force.

auth_setupB

Save a ready-made direct OAuth token (y0_...) into a direct auth profile; use auth_login for the interactive browser flow. Call tool_help('auth_setup') for parameters.

Inputs: code (required), login, profile.

auth_statusC

Check the current direct auth profile status (token presence, login, expiry). Call tool_help('auth_status') for parameters.

Inputs: profile.

changes_checkA

Check what changed since a timestamp within specific objects, filtered by exactly one of campaign_ids / ad_group_ids / ad_ids. Use this for targeted checks; use changes_check_campaigns for an account-wide campaign-level scan. Call tool_help('changes_check') for parameters.

Inputs: timestamp (required), field_names, fields, campaign_ids, +2 more.

changes_check_campaignsA

Check account-wide campaign-level changes since a timestamp (which campaigns changed). Use this for a broad scan; use changes_check to drill into specific campaign/ad-group/ad IDs. Call tool_help('changes_check_campaigns') for parameters.

Inputs: timestamp (required).

changes_check_dictionariesB

Check whether Yandex.Direct reference dictionaries (e.g. regions) have changed; takes no parameters. Call tool_help('changes_check_dictionaries') for parameters.

Inputs: no named parameters.

dictionaries_getB

Get reference dictionary data by names (Currencies, GeoRegions, TimeZones, etc.); use dictionaries_list_names to see options. Call tool_help('dictionaries_get') for parameters.

Inputs: names (required).

dictionaries_get_geo_regionsC

Get GeoRegions dictionary entries, optionally filtered by name or region IDs. Call tool_help('dictionaries_get_geo_regions') for parameters.

Inputs: fields (required), name, region_ids, exact_names.

dictionaries_list_namesA

List the dictionary names accepted by dictionaries_get. Call tool_help('dictionaries_list_names') for parameters.

Inputs: no named parameters. Returns: result

keywordsresearch_deduplicateC

Deduplicate a list of keywords. Call tool_help('keywordsresearch_deduplicate') for parameters.

Inputs: keywords (required).

keywordsresearch_has_search_volumeC

Check whether keywords have search volume in given regions. Call tool_help('keywordsresearch_has_search_volume') for parameters.

Inputs: keywords (required), region_ids (required), fields.

leads_getB

List leads (form submissions) for the given Turbo pages; leads are scoped to Turbo pages, not campaigns. Call tool_help('leads_get') for parameters.

Inputs: turbo_page_ids (required), datetime_from, datetime_to, limit, +2 more.

reports_customA

Build an arbitrary Yandex.Direct statistics report: any FieldNames, filters, ordering, date/week/month/goal breakdowns, pagination, and file output. Use reports_custom for arbitrary fields & breakdowns; use reports_get for a quick recent snapshot. Call tool_help('reports_custom') for parameters.

Inputs: field_names (required), date_from, date_to, report_type, +21 more. Returns: result

reports_getA

Quick per-campaign performance snapshot over a short recent window (~last 8 days, default fields). Use reports_get for a fast overview; use reports_custom for arbitrary fields, filters, or date/goal breakdowns. Call tool_help('reports_get') for parameters.

Inputs: date_from, date_to. Returns: result

reports_list_typesA

List supported Yandex.Direct report types with guidance on when to pick each (use before reports_custom if unsure which report_type fits). Call tool_help('reports_list_types') for parameters.

Inputs: no named parameters. Returns: result

tool_helpA

Get the full documentation for another tool: parameter reference, examples and constraints. Call this BEFORE using an unfamiliar tool — the tools themselves carry only a one-line summary. Pass the exact tool name (e.g. 'campaigns_add'); omit the name to list every available tool.

Inputs: name.

v4events_get_events_logC

Get v4 Live events log entries via GetEventsLog for a timestamp range. Call tool_help('v4events_get_events_log') for parameters.

Inputs: timestamp_from (required), timestamp_to (required), currency, limit, +2 more. Returns: result

v4forecast_createC

Create a v4 Live budget forecast via CreateNewForecast (up to 100 phrases). Call tool_help('v4forecast_create') for parameters.

Inputs: phrases (required), geo_ids, currency, dry_run. Returns: result

v4forecast_getC

Get a ready v4 Live budget forecast by ID via GetForecast. Call tool_help('v4forecast_get') for parameters.

Inputs: forecast_id (required). Returns: result

v4forecast_listA

List v4 Live budget forecasts via GetForecastList. Call tool_help('v4forecast_list') for parameters.

Inputs: no named parameters. Returns: result

v4goals_get_retargeting_goalsB

Get retargeting goals for campaigns (v4 Live); use v4goals_get_stat_goals for Metrica stat goals. Call tool_help('v4goals_get_retargeting_goals') for parameters.

Inputs: campaign_ids (required). Returns: result

v4goals_get_stat_goalsB

Get Yandex Metrica stat goals available for campaigns (v4 Live); use v4goals_get_retargeting_goals for retargeting goals. Call tool_help('v4goals_get_stat_goals') for parameters.

Inputs: campaign_ids (required). Returns: result

v4keywords_get_suggestionA

Get related keyword suggestions via v4 Live GetKeywordsSuggestion (up to 20 phrases; spends API points). Call tool_help('v4keywords_get_suggestion') for parameters.

Inputs: keywords (required). Returns: result

v4wordstat_create_reportB

Create a v4 Live Wordstat report via CreateNewWordstatReport (up to 10 phrases). Call tool_help('v4wordstat_create_report') for parameters.

Inputs: phrases (required), geo_ids, dry_run. Returns: result

v4wordstat_get_reportC

Get a ready v4 Live Wordstat report by ID via GetWordstatReport. Call tool_help('v4wordstat_get_report') for parameters.

Inputs: report_id (required), dry_run. Returns: result

v4wordstat_list_reportsC

List v4 Live Wordstat reports via GetWordstatReportList. Call tool_help('v4wordstat_list_reports') for parameters.

Inputs: dry_run. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored 2026-06-21 12:35 across 26 tools

Disambiguation5/5

Each tool has a clearly distinct purpose, grouped by functional area (auth, changes, dictionaries, keywordsresearch, leads, reports, v4*). Within groups, create/get/list patterns are well-separated, and descriptions clarify any potential overlap.

Naming Consistency5/5

Tool names follow a consistent area_verb pattern (e.g., auth_login, dictionaries_get, v4forecast_create). The only exception is tool_help, a meta tool. All others adhere to snake_case and predictable naming.

Tool Count4/5

26 tools is slightly above the typical 3-15 range, but it is justified by the breadth of features covered (authentication, changes, dictionaries, keyword research, leads, reporting, v4 Live API). The organization keeps it manageable.

Completeness2/5

The tool set focuses on data retrieval and analysis (reports, dictionaries, changes, forecasts) but lacks core campaign management operations such as creating, updating, or deleting campaigns, ad groups, or bids. This limits its completeness for full Yandex Direct management.

Resources

Related MCP Connectors

google-ads
ai.adramp
Google Ads MCP server — manage campaigns, keywords, and metrics.
Marketing E-commerce & Retail
2
https://mcp.adramp.ai
Yandex Tools MCP
io.github.ruslan-mm18
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
Search Marketing Monitoring
168
https://mcp.seyka.ru/mcp
Lemonado
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
https://mcp.lemonado.io/mcp
Kontekstolog — Yandex Direct, Metrika & Wordstat
online.kontekstolog
Yandex Direct, Metrika & Wordstat MCP for Russian digital marketing.
Marketing Search
1
https://kontekstolog.online/mcp

Related MCP Servers

yandex-direct-mcp
Marketing
theYahia
A
license
A
quality
C
maintenance
MCP server for Yandex.Direct API v5 enabling management of campaigns, ad groups, ads, keywords, statistics, and account info via 12 tools.
Updated 2 months ago (2026-09-06 08:41 UTC)
20
92 npm
4
MIT
yandex-marketing-mcp
Marketing Search
skiddgoddamn
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.
Updated 16 days ago (2026-10-29 02:02 UTC)
100
14 npm
3
MIT
yandex-mcp
Marketing Search
SvechaPVL
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.
Updated 4 months ago (2026-07-02 02:34 UTC)
58
MIT
yadirect-mcp
Marketing Search
Lermont
A
license
A
quality
C
maintenance
A local MCP server that connects Yandex Direct advertising reports and safe campaign creation to AI agents, enabling natural-language analytics and protected campaign setup.
Updated 12 days ago (2026-11-01 17:26 UTC)
8
2
MIT

yandex-direct-mcp

Профили и поверхность инструментов

Переменные окружения

Установка

Claude Code (рекомендуемый способ — uvx)

.claude.json / Cursor / другие MCP-клиенты

Запуск standalone (без MCP-клиента, для проверки)

Первый вход (OAuth / PKCE)

Включение управления кампаниями и финансов

(Опционально) Запуск как Claude Code плагин

Документация

Лицензия

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

yandex-direct-mcp

yandex-marketing-mcp

yandex-mcp

yadirect-mcp

`.claude.json` / Cursor / другие MCP-клиенты