Yandex Direct MCP

Yandex Direct MCP connects an AI app to your Yandex Direct advertising account. Ask in plain language where your ad budget is going, compare campaigns, ads, and keywords, then prepare or make the changes you need without switching between account sections. Setup starts right in the conversation: no need to create a token or edit configuration in advance.

• 44 tools. Campaigns, ad groups, ads, keywords, bids, adjustments, extensions, statistics, balance, reference books, and account connection right in the conversation.

• Two ways to connect. A remote server by URL requires no manual token retrieval and is read-only; a local one via npx gives full access to the account.

• In-chat connection. Yandex opens a sign-in page; after the code from the chat you can start working with ads right away, and access is renewed automatically.

• Money in a readable format. Convenient tools show budgets, bids, and balance in the account currency rather than API micro-units.

• Real advertising. Local changes are applied to the live account and can affect spending. For testing, Yandex Direct sandbox is available.

Try it with your first message:

Show me the campaigns in my account and last week's spend by ad group.

Connect the server · See scenarios · Open technical documentation

See it working in a minute

You: Connect Yandex Direct.

Assistant: Gives you a link to sign in to Yandex. Open it under the account with access to the desired advertising account, confirm access, and send back the code shown.

You: Sends the code from the Yandex page.

Assistant: Connects Direct and shows the account. No need to restart the app.

You: Show me the campaigns in my account and last week's spend by ad group.

Assistant: Finds the campaigns, builds a report by ad group, and shows spend in the account currency.

Related MCP server: Yandex Direct MCP Server

Table of contents

• Quick start

• What you can delegate

• How it works

• What can change data

• Connection and configuration

• Data and telemetry

• Limitations

• Technical documentation

• Support

Quick start

1. Choose a connection method and add the server to your AI app using the instructions below.

2. Open a new conversation and ask: "Show me the campaigns in my account and last week's spend by ad group."

Analysis without getting a token yourself — by URL

The remote server https://mcp.askads.ru/mcp connects through an app that supports MCP by URL. Sign in to Yandex in your browser and confirm access: no token needs to be passed in the config. This option is read-only — for statistics, audits, and viewing objects; it does not change ad settings.

In Claude Code you can add it with the command:

claude mcp add --transport http yandex-direct https://mcp.askads.ru/mcp

After connecting, open /mcp and complete authorization. In other apps that support HTTP MCP, add the same URL through the app interface.

Full access — locally via npx

Creating and modifying objects requires Node.js 20+. npx downloads the server on first launch — no separate package installation needed. No need to obtain a token in advance — connection starts right in the conversation:

1. Add the server to your AI app — an example for Codex is open below; other apps are collected in collapsible instructions.

2. Write: "Connect Yandex Direct" — the assistant will walk you through signing in to Yandex and show the account.

For CI and agent setups — a ready-made token and YANDEX_DIRECT_LOGIN, see Connection and configuration.

Through the app interface:

1. Open Settings → Plugins → MCP servers.

2. Click Add server.

3. Add the launch command npx -y mcp-yandex-direct@latest.

Through the command line:

codex mcp add yandex-direct -- npx -y mcp-yandex-direct@latest

Check the connection:

codex mcp list

Official Codex instructions

claude mcp add --transport stdio --scope user yandex-direct -- npx -y mcp-yandex-direct@latest

Check the connection: claude mcp list.

Open Settings → Developer → Edit Config and add to claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

If there is no Developer section, open the file manually: macOS — ~/Library/Application Support/Claude/claude_desktop_config.json, Windows — %APPDATA%\Claude\claude_desktop_config.json. Restart Claude Desktop.

Open ~/.cursor/mcp.json to connect the server in all projects, or .cursor/mcp.json in a specific project. Add:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

In the command palette, run MCP: Open User Configuration. In the opened mcp.json, add the server:

{
  "servers": {
    "yandex-direct": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}

After saving, run MCP: List Servers and start the server from the list.

What you can delegate

Check how the budget is being spent

• "Which campaigns spent the most last week?"

• "Which ads are getting impressions and clicks but no conversions?"

• "Compare spend, CTR, and average CPC across campaigns for the month."

• "Show the account balance and the remaining daily API quota."

Find areas for improvement

• "Which keywords are spending budget but getting no clicks?"

• "Which ad groups and ads are currently paused or failing moderation?"

• "Check which bid adjustments are active for mobile devices."

• "What sitelinks and refinements does this campaign have?"

Prepare changes

• "Suggest new bids for high-CTR keywords and show the changes before applying."

• "Check whether the campaign has negative keywords for this topic and prepare a list."

• "Put together the parameters for a new text campaign for Moscow: budget, ad groups, keywords, and ads."

Perform an explicit action

• "Add these keywords to group 123 and set the bid to 45 ₽."

• "Pause ad 456."

• "Upload the page with the image to the ad library."

How it works

Advertising is usually built from three levels: campaign → ad group → ad. The ad group contains keywords, serving settings, and bid adjustments. Ads can have sitelinks, refinements, business cards, and images.

The server helps you look at these objects together: link campaign spend with ad group statistics, keywords, and ads. It can create new campaigns and ads of the text type only. Campaigns of other types can be read, renamed, have their budgets changed, be paused, archived, and deleted by ID.

Statistics are not generated instantly: get_statistics launches a report in the Reports service and waits for it to be ready. Large lists are paginated automatically by autoPaginate.

What can change data

The remote server by URL only reads data. The local server via npx can change a live advertising account:

The tools pass read, write, and potentially irreversible action labels to the AI app. The app may show a confirmation, but its behavior depends on the client. A direct API request will additionally not perform a write without confirmWrite=true; changing ads requires an explicit request.

Connection and configuration

For normal use, no token is needed in advance:

1. Ask in the chat to connect Yandex Direct.

2. Open the Yandex OAuth link under the account with access to the desired advertising account.

3. Confirm access and send the displayed code back in the chat. That's it — you can work with ads: no need to restart the client or edit the configuration.

From then on, the connection lives on its own: access is renewed automatically and does not expire after a year. To check the status, ask "show connection status"; to disconnect, say "disconnect Direct". The granted access can be revoked in Yandex ID.

For CI and automated setups where there is no conversation, configuration via environment variables is available:

You can get a ready-made token for YANDEX_DIRECT_TOKEN via the link, signing in under the account with access to the desired account:

Get a Yandex Direct token

Do not publish the token in chats, repositories, or screenshots: it grants access to the advertising account, including actions that may affect the budget.

Data and telemetry

By default, the server sends anonymous technical events: a random installation identifier, the name of the invoked tool, server versions, AI application, Node.js, and operating system. This is needed to understand which parts of the server are used and whether problems occur at startup. The Yandex token, advertising account data, tool arguments, request texts, values, and names of environment variables are not sent.

To disable telemetry for Ask Ads MCP servers, set the environment variable:

ASKADS_TELEMETRY=0

Limitations

• Daily API quota. Each call consumes Units. The get_quota tool shows how much has been spent, how much remains, and what is available for today.

• Report limits. Yandex reports have their own limits on volume and quantity per day, and report readiness in the Reports service requires waiting.

• Large lists. If the internal limit is reached during automatic pagination, the server explicitly marks the result as incomplete rather than hiding this fact.

• Temporary errors. The server makes up to three retries under rate limits. Network and server errors are automatically retried only for read operations, so as not to duplicate a change.

• Production account. Local changes are applied to the real advertising account and may affect spending. For tests, use the sandbox (YANDEX_DIRECT_SANDBOX=true).

• No continuous monitoring. The server runs during a call from the AI application. If the application supports scheduled tasks, you can set up a periodic request to check the needed metrics.

Technical documentation

• MCP capabilities catalog — pages on user tasks for each tool.

• All tools — parameters, responses, and boundaries of each tool.

• Development — project structure and working with the source code.

• Yandex Direct API — the primary source on the API and its limitations.

• npm package — published server versions.

Support

Found a bug or missing a scenario? Create an issue or write to Telegram.