Yandex Direct MCP

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.gitcd yandex-mcp && bun installnode packages/yandex-direct-mcp/src/index.mjs

Configuration

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

Tools

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:

{ "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 statisticsare 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 noAPI 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