yandex-direct-mcp

MCP server for Yandex Direct API v5 — campaigns, ad groups, ads, keywords, bids, bid modifiers, sitelinks, vCards, and reports. 43 tools.

Write access, no dry-run. Unlike the other servers in this monorepo, this one changes live advertising data: it can create, update, delete and archive campaigns and ads, and set bids (in micro-units — a factor-of-1,000,000 mistake is a real risk). There is no confirmation step and no dry-run mode. Point it at the sandbox (YANDEX_DIRECT_SANDBOX=true) until you trust the workflow.

Installation

This package is published as @stufently/yandex-direct-mcp; unscoped yandex-*-mcp names on the public registry belong to an unrelated publisher (see the note in the root README). Nothing is on the scope yet, so run it from source:

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp && bun install
node packages/yandex-direct-mcp/src/index.mjs

Configuration

| Variable | Required | Description | |----------|----------|-------------| | YANDEX_DIRECT_TOKEN | yes | OAuth token for Direct API v5 | | YANDEX_DIRECT_CLIENT_LOGIN | agencies only | Client login to act on behalf of | | YANDEX_DIRECT_SANDBOX | no | true routes calls to the Direct sandbox |

{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-direct-mcp/src/index.mjs"],
      "env": { "YANDEX_DIRECT_TOKEN": "your-token" }
    }
  }
}

Tools

| Area | Tools | |------|-------| | Campaigns | get_campaigns, add_campaigns, update_campaigns, delete_campaigns, archive_campaigns, unarchive_campaigns, suspend_campaigns, resume_campaigns | | Ad groups | get_adgroups, add_adgroups, update_adgroups, delete_adgroups, archive_adgroups, unarchive_adgroups | | Ads | get_ads, add_ads, update_ads, delete_ads, archive_ads, unarchive_ads, moderate_ads | | Keywords | get_keywords, add_keywords, update_keywords, delete_keywords, suspend_keywords, resume_keywords | | Bids | get_keyword_bids, set_keyword_bids, set_auto_keyword_bids, get_bid_modifiers, add_bid_modifiers, set_bid_modifiers, delete_bid_modifiers | | Extensions | get_sitelinks, add_sitelinks, delete_sitelinks, get_vcards, add_vcards, delete_vcards | | Other | create_report, get_dictionaries, get_clients |

Irreversible tools need confirm: true

Fourteen tools cannot be undone through this API, and this is the one server where a mistaken call spends real money. They refuse unless the call carries confirm: true:

| Family | Tools | Why it cannot be undone | |--------|-------|-------------------------| | Deletes | delete_campaigns, delete_adgroups, delete_ads, delete_keywords, delete_bid_modifiers, delete_sitelinks, delete_vcards | The entity and the statistics attached to it are gone; add_* creates a new entity with a new ID, not the old one back | | Updates | update_campaigns, update_adgroups, update_ads, update_keywords | Fields are overwritten in place and Direct exposes no revision history, so the previous ad text, budget or strategy cannot be read back | | Bids | set_keyword_bids, set_auto_keyword_bids, set_bid_modifiers | Same overwrite, with a price tag: these are the numbers that decide what the account pays per click |

{ "ids": [12345], "confirm": true }

Called without it, the tool returns an error result and sends nothing to the Direct API — no entity touched, no bid moved, no API units spent:

Refused: `delete_campaigns` requires explicit confirmation.

Target — IDs: 12345. Deleting campaigns is irreversible: they and their accumulated statistics
are gone for good, and Yandex Direct offers no way to restore them.

Nothing was sent to the Yandex Direct API — no campaign, ad, keyword or bid was touched, and no
API units were spent.

To go ahead, call `delete_campaigns` again with the same ids and `confirm: true`.
To see the current state first, call `get_campaigns`.

confirm is optional in the JSON schema on purpose: a missing confirmation has to come back as that explanation, not as a schema validation error a model cannot act on. Only a literal true counts — "true", 1 and "yes" are refused, because a guess at the protocol is not a decision to spend money. All fourteen carry destructiveHint: true in their MCP annotations, so clients that surface tool risk can show it before the call.

add_*, archive_*/unarchive_*, suspend_*/resume_* and moderate_ads are deliberately left unguarded. Each has an inverse in this same server (or, for moderate_ads, leaves the entity itself untouched), so they are changes rather than losses. Guarding every write would train callers to pass confirm: true by reflex — which is exactly what would defeat it on the fourteen calls that matter.

Bids are expressed in micros (×10⁶). Set YANDEX_DIRECT_SANDBOX=true while experimenting.

Known limitations

• The API path is hard-coded to /json/v5, so the unified performance campaigns endpoint (v501) is unreachable.
• The Units response header (points consumed / remaining) is not surfaced, so a client cannot see how much of its quota a call cost.

License

MIT