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

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

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.

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

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

License

MIT — see LICENSE.