yandex-direct-mcp

# @theyahia/yandex-direct-mcp MCP Server for Yandex.Direct API — managing contextual advertising from any MCP client (Claude, Cursor, etc.): campaigns, groups, ads, keywords, **bids**, **negative phrases**, statistics, balance. **20 tools.** [](https://www.npmjs.com/package/@theyahia/yandex-direct-mcp) [](https://opensource.org/licenses/MIT) > Money — **in rubles** (budgets, bids on input and output); the server converts to microunits of the API. **Sandbox** is supported for safe testing and **agent mode** (Client-Login). ## Installation ### Claude Desktop ```json { "mcpServers": { "yandex-direct": { "command": "npx", "args": ["-y", "@theyahia/yandex-direct-mcp"], "env": { "YANDEX_DIRECT_TOKEN": "your_token" } } } } ``` ### Claude Code ```bash claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=your_token -- npx -y @theyahia/yandex-direct-mcp ``` ## Configuration (environment variables) | Variable | Required | Purpose | |------------|:-----------:|------------| | `YANDEX_DIRECT_TOKEN` | yes | OAuth token for Yandex.Direct | | `YANDEX_DIRECT_SANDBOX` | no | `1` — work in [sandbox](https://yandex.com/dev/direct/doc/concepts/sandbox.html) (isolated data, no spending). Same token, different URL | | `YANDEX_DIRECT_LOGIN` | no | Client login for agent tokens (header `Client-Login`). Required if the token is agent | ### How to get a token The OAuth token is issued for an application registered in [Yandex OAuth](https://oauth.yandex.com/), with access to the Direct API. Details — [registering an application and obtaining a token](https://yandex.com/dev/direct/doc/start/token.html). Access to the API needs to be [requested in the Direct interface](https://yandex.com/dev/direct/doc/start/step1.html). ## ⚠️ Attention: real spending Tools `create_campaign`, `create_text_ad`, `add_keywords`, `set_keyword_bids`, and others change the live advertising account and can **spend money**. For debugging scenarios, enable sandbox mode (`YANDEX_DIRECT_SANDBOX=1`). ## Tools (20) **Campaigns** | Tool | Description | |------------|----------| | `list_campaigns` | List of campaigns (filter by status/type, pagination) | | `get_campaign` | Detailed information about a campaign by ID | | `create_campaign` | Create a campaign (budget in rubles, strategy selection) | | `update_campaign` | Update name/budget and/or status (SUSPEND/RESUME/ARCHIVE/UNARCHIVE) | **Ad Groups** | Tool | Description | |------------|----------| | `list_ad_groups` | Ad groups of selected campaigns | | `create_ad_group` | Create a group with targeting by regions | | `delete_ad_groups` | Delete groups by ID | | `set_ad_group_negative_keywords` | Set negative keywords for a group | **Ads** | Tool | Description | |------------|----------| | `list_ads` | Ads in groups | | `create_text_ad` | Create a text ad (≤56/≤30/≤81) | | `update_text_ad` | Update title/text/link | | `manage_ads` | suspend/resume/archive/unarchive/moderate/delete | **Keywords and Bids** | Tool | Description | |------------|----------| | `list_keywords` | Keywords in groups (bids in rubles) | | `add_keywords` | Add keywords | | `set_keyword_bids` | Set bids (search/network, rubles) on phrases/groups/campaigns | | `manage_keywords` | suspend/resume/delete | | `set_campaign_negative_keywords` | Set negative keywords for a campaign | **Statistics, Account, References** | Tool | Description | |------------|----------| | `get_statistics` | Statistics for a period (impressions, clicks, spending, CTR, CPC) | | `get_account_balance` | Account balance (Live API v4) | | `get_regions` | Directory of region codes (225 = Russia) | ## Query Examples ``` Show all active advertising campaigns Create a campaign "Summer Sale" with a budget of 5000 ₽/day, start 2026-05-01 Set a bid of 25 ₽ on keywords 111 and 222 Add negative keywords "free", "download" to campaign 12345 What is the statistics for campaigns 12345 and 67890 for the last week? Find the region code for Novosibirsk Show account balance ``` ## Development ```bash npm install npm run build # tsc → dist/ npm test # vitest (mocks fetch) npm run dev # tsx src/index.ts ``` ## License MIT