Skip to main content
Glama
yandex-direct-mcp

yandex-direct-mcp

by iarbor04

yandex-direct-mcp

MCP server for Yandex Direct API v5. Connects an advertising account to an AI agent (Claude Code, Cursor, and any other MCP client): the task is set in plain text, the agent itself assembles the necessary API calls and parses the response.

Ты:    посмотри, куда за август ушёл бюджет и что откручивается без конверсий
Агент: [direct_report] → 12 кампаний, 340 фраз
       Расход 214 800 ₽. Кампания «Поиск / Бренд» — 38%, CPA 610 ₽.
       17 фраз потратили 31 400 ₽ при нуле конверсий — вот они, отключаем?

No dependencies: a single Node.js file, stdio transport, requests via built-in fetch.

  • Token is stored locally in a file with 600 permissions and goes nowhere except api.direct.yandex.com.

  • Changes require confirmation. The MCP client asks permission for each call; plus there is a "read-only" mode that blocks mutating methods at the server level.

  • Full API, not a subset. The universal direct_call tool covers all v5 services — from campaigns to keywordsresearch.

What you can do

Analytics. Reports for any slice and period: campaigns, groups, ads, key phrases, search queries, geo, devices, time of day, gender and age. Spend, clicks, CTR, CPC, conversions, CPA, period comparison. Parsing search queries for junk, finding phrases with spend without conversions.

Management. Creating and editing campaigns, groups, ads, key phrases. Bids and daily budgets — including in bulk, by rule ("CPA above 2000 ₽ → cut bid by 20%"). Minus words, enabling and pausing, sending for moderation, bid adjustments by geo, devices and audiences, retargeting.

Semantics. Checking phrase frequency (keywordsresearch), reference books for regions and time zones (dictionaries).

Scheduled tasks. Morning spend summary for yesterday, weekly search query analysis, overspend alert — if the MCP client supports scheduling.

Detailed scenarios with example queries: docs/usage.md.

Related MCP server: Yandex MCP Server

Requirements

  • Node.js 18 or newer (built-in fetch required).

  • Yandex Direct account.

  • A registered application on oauth.yandex.ru with an approved request for API access. This is the main barrier, and it takes from an hour to three days — start with it: docs/registration.md.

Installation

git clone https://github.com/iarbor04/yandex-direct-mcp.git
cd yandex-direct-mcp

No dependencies, npm install not needed.

Claude Code:

claude mcp add yandex-direct --scope user -- node "$PWD/server.js"

Cursor, Windsurf and other clients with JSON config:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/абсолютный/путь/yandex-direct-mcp/server.js"]
    }
  }
}

Tools appear when the client starts — after adding the server, restart the session.

Authorization

Order matters. If you don't do it in this order, you'll get error 58 and waste time — we did.

1. Request for API access

You register an application on oauth.yandex.ru and submit a request in the Direct interface: “My requests”. Review takes place on Russian business days from 10:00 to 19:00, from an hour to three days, up to seven days during peak periods.

What to write in the form (ready-made texts for all fields, including the interaction scheme description and diagram) — docs/registration.md.

Without an approved request, even the sandbox doesn't work. Verified: api-sandbox.direct.yandex.com returns the same error 58 as the production API. You won't be able to debug “on test data”.

2. Token

./save-token.sh <CLIENT_ID>

The script will show an authorization link, wait for you to paste the address bar after the redirect (input is hidden — neither URL nor token go into shell history), extract access_token, put it in ~/.config/yandex-direct/token with 600 permissions, and immediately run an access check.

<CLIENT_ID> is the identifier of the application for which the request was approved. The script will remember it in config.json, then you can run it without an argument.

Manually the same: open https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>, take the token from the address bar after #access_token= (before &) and put it in a file.

3. Verification

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

Or just ask the agent: “check access to Direct”. A successful response shows the login, account currency, and remaining points.

Pitfalls we ran into

Symptom

Cause

What to do

error 58 — “Incomplete registration”, although the request is approved

Token obtained under a different application, not the one for which the request was approved. Easy to run into if there are several applications

Open the approved request, check Client ID, get the token specifically under it

error 58 in sandbox

The sandbox also requires an approved request

Wait for approval, no workaround

Repeated authorization returns the same token

Yandex returns the already issued token until access to the application is revoked

Revoke access at id.yandex.ru/personal/data-access, then authorize again

error 53 — “Invalid OAuth token”

Token revoked, expired, or copied with truncation

Get it again via ./save-token.sh

clients.get responds, but campaigns.get returns an empty list

Token issued under a login that has no campaigns

Get a token under the required login. No need to re-apply: it is approved for the application, not for the user

The request must be submitted again after recreating the application

Approval is tied to Client ID, not to the account

Don't delete the approved application. If you deleted it — new request, refer to the previous Client ID in the description

Separately: the token must not be pasted into the agent chat — it will end up in the conversation history. That's why save-token.sh with hidden input was made. If you did paste it — revoke access at id.yandex.ru/personal/data-access and get a new one.

Tools

Tool

Purpose

direct_status

Whether there is a token, which environment, whether access is alive (test clients.get), remaining points. Token is not revealed

direct_reference

Cheat sheet: services, methods, params examples, report types, bid units, limits

direct_call

Universal call POST /json/v5/{service} with body {method, params}

direct_report

Reports API: sends ReportDefinition, waits for readiness (codes 201/202), returns TSV

Configuration

~/.config/yandex-direct/config.json:

{
  "token": "",
  "client_id": "…",
  "client_login": "",
  "sandbox": false
}

The token is read on each call — after replacing it, the server does not need to be restarted.

Environment variable

Meaning

YANDEX_DIRECT_TOKEN

Token directly, takes priority over files

YANDEX_DIRECT_CLIENT_LOGIN

Client login for agency account (Client-Login header)

YANDEX_DIRECT_SANDBOX=1

Work with the sandbox

YANDEX_DIRECT_READONLY=1

Block add, update, delete, suspend, resume, moderate, set

YANDEX_DIRECT_CONFIG_DIR

Different configuration directory

Token search order: YANDEX_DIRECT_TOKEN → config.json → ~/.config/yandex-direct/token.

Limits and cost

Each call spends points (Units); the remainder comes in the response header and is printed in the result header. A regular get is about 10 points, reports are more expensive. The daily limit depends on the account (for a regular client — about 160,000, enough for live work with a margin).

The get method returns a maximum of 10,000 objects at a time — then page by page via LimitOffset. Bids are set in micro-units: 30000000 = 30 ₽. The report's ReportName must be unique, otherwise Direct will return a previously generated report.

Interaction scheme

Interaction scheme with Yandex Direct API

Source: docs/scheme.html — useful if you need your own version of the image for the request.

License

MIT — see LICENSE.

Available Tools

4 tools
direct_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

    A4.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables managing Yandex Direct PPC campaigns, ad groups, ads, and keywords, plus pulling performance statistics via the Yandex Direct API v5.
      46
      641 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Yandex Direct advertising campaigns, ads, keywords, and reports via natural language using the Yandex Direct API v5.
      2
      1
      MIT