yandex-direct-mcp

MCP server for managing Yandex Direct ad campaigns via AI assistants (Claude Code, Claude Desktop, ChatGPT, etc.).

Pure Ruby, no external dependencies. 30 tools for a complete advertising workflow: creating campaigns, writing ads, selecting keywords, analytics.

Features

Quick Start

1. Create an OAuth Application

1. Go to oauth.yandex.ru and create a new application
2. Platform type: Web services
3. Redirect URI: https://oauth.yandex.ru/verification_code
4. Permissions: Yandex.Direct — Use Yandex.Direct API

2. Confirm API Access

After creating the OAuth application, you need to submit a request for full access to the Yandex Direct API:

1. Sign in to Yandex Direct
2. Go to Tools → API (or use the direct link: https://direct.yandex.ru/registered/main.pl?cmd=apiSettings)
3. Open the "My requests" tab → "New request"
4. Fill out the form:
   • Application: select your OAuth application from the list
   • Contact: your email
   • Type of work: "Direct advertiser automating management of own campaigns"
   • Programming language: Ruby
   • Protocol: JSON
   • Logins: your Yandex Direct login
5. Submit the request — the API starts working immediately after submission (status "new")

Without this step, the API will return an "Incomplete registration" error (code 58).

3. Obtain an OAuth Token

Open the following URL in your browser (replace with your Client ID):

https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID

Sign in and copy the token from the address bar.

4. Connect to Claude Code

Add the following to your project's .mcp.json:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "ruby",
      "args": ["/path/to/yandex-direct-mcp/bin/server"],
      "env": {
        "YANDEX_DIRECT_TOKEN": "your_oauth_token"
      }
    }
  }
}

Or add it to the global config ~/.claude.json (under the mcpServers section) to make the server available across all projects.

For Claude Desktop — add the same configuration to ~/Library/Application Support/Claude/claude_desktop_config.json.

5. Start Using It

Once connected, the AI assistant will have access to all 30 tools and will be able to manage your campaigns via chat:

• "Show my campaigns"
• "Create a campaign to promote a book with a budget of 500 RUB/day"
• "Add keywords: read online, new books 2026"
• "Show statistics for the last week"
• "What search queries are bringing customers?"
• "Pause the campaign"
• "Update the ad text"

Note: The budget currency is determined by the Yandex Direct account (rubles, tenge, etc.). The daily_budget parameter specifies the amount in the account's primary currency.

Limitations

• SMB campaigns (created via the simplified Yandex Direct wizard) are not visible through the API — only TEXT_CAMPAIGN type campaigns
• Callouts can be created via the API, but can only be linked to an ad through the web interface
• Images can only be uploaded via URL or base64 — local files must first be hosted or encoded
• Yandex requires a landscape image (minimum 1080x607) for text & image ads

Sandbox Mode

For testing without real expenses, add the YANDEX_DIRECT_SANDBOX environment variable:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "ruby",
      "args": ["/path/to/yandex-direct-mcp/bin/server"],
      "env": {
        "YANDEX_DIRECT_TO

... [View full README on GitHub](https://github.com/vtka/yandex-direct-mcp#readme)