Yandex Ads MCP Server
An MCP server for Yandex Direct, Metrica, Audiences and Wordstat with read-only mode and change confirmation
Install
git clone https://github.com/Yurich-ru/yandex-ads-mcp.git
cd yandex-ads-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txtAfter install copy .env.example to .env and fill in the tokens.
This is third-party code. Review the repository files before installing.
What it does
The server covers the Yandex advertising cycle from one place. In Direct the agent creates and changes campaigns, ad groups, ads including responsive ones, keywords and autotargeting, bids, bid modifiers, negative keywords and extensions, and pulls reports. Metrica offers counters, goals, segments, reports and uploads of offline conversions and costs; Audiences builds segments from CRM data, lookalikes and geo segments; Wordstat gives volumes, trends and regions. For live accounts it has read-only mode, a preview mode that requires confirmation, a client login allowlist and multi-account support.
Who it is for. For PPC specialists and agencies running Yandex Direct campaigns.
Good fit when
- You need to bulk-create ad groups, ads and keywords in Direct from a plan
- You want Direct costs matched against Metrica goals in one report
- An agency needs to work across several client accounts with restricted access
Not a fit when
- You only need Wordstat without ad account access
- You are not ready to enable YD_READONLY or YD_CONFIRM on a live account
Example request
Show last week's Direct costs and conversions by campaign and suggest where to lower bids without changing anything until I confirmLimitations
Requires your own Yandex OAuth app with Direct, Metrica, Audiences and Yandex Cloud access, plus an approved Direct API application. Wordstat needs a Yandex Cloud billing account with a folder and the search-api.executor role, and newer tokens also need a service account API key. There is no package; install from a clone into a Python virtualenv. Safety modes are off by default, and the repository has no license file.
How to disable. Remove the yandex-ads block from ~/.claude.json or the client config and revoke the OAuth token in Yandex ID settings.
MCP
- Transport
- stdio
- Authentication
- OAuth
| Environment variables | |
|---|---|
| YD_OAUTH_TOKEN required, secret | OAuth token with Direct, Metrica, Audiences and Yandex Cloud access |
| YC_FOLDER_ID | Yandex Cloud folder ID for Wordstat |
| YC_API_KEY secret | Service account API key for Wordstat |
| YD_READONLY | true blocks all write tools |
| YD_CONFIRM | true requires confirmation for each change |
| YD_ALLOWED_LOGINS | Allowlist of agency client logins |
| YD_SANDBOX | true enables the Direct sandbox |
Security check
- Creates campaigns and changes bids and budgets in the live account, spending money
- Uploads customer CRM data such as emails and phones to Audiences
- Safety modes are off by default
README in short
The Russian README covers installing from a clone into a virtualenv and connecting to Claude Code. It details getting an OAuth token, applying for Direct API access and setting up Yandex Cloud for Wordstat. It includes an environment variable table, a section on safety modes and multi-account use, and a full tool list per service with parameter examples for complex calls.
FAQ
How do I stop the agent from changing a live campaign by accident?
Set YD_READONLY=true to block write tools before any network call, or YD_CONFIRM=true so each change first returns a preview and runs only with confirm=true.
What if Direct and Metrica are in different accounts?
Issue a token in each account and set YD_OAUTH_TOKEN for Direct and YD_METRIKA_TOKEN and YD_AUDIENCE_TOKEN for Metrica and Audiences.
Related
Marketing Skills for AI agents
Marketing Skills for AI Agents
About fifty skills for CRO, copywriting, SEO, analytics, ads and launches, built for coding agents
A skill that strips AI writing tells from text using Wikipedia's list, without adding invented facts
Content skills: article illustrations, covers, infographics, comics, translation, URL to Markdown and social posting
The Chinese version of Humanizer: finds and removes signs of AI writing in Chinese text