yandex-wordstat-mcp

MCP server for Yandex Wordstat API — keyword research and search trend analysis for the Russian market.

English | Русский

English

Features

| Tool | Description | Quota Cost | |------|-------------|------------| | get-regions-tree | Get top 3 levels of region hierarchy (configurable depth) | Free | | get-region-children | Drill down into a specific region to see its children | Free | | top-requests | Popular queries containing a keyword (last 30 days) | 1 unit | | dynamics | Search volume trends over time | 2 units | | regions | Regional distribution with region names and affinity insights | 2 units |

v1.2.0 Improvements:

• Smart region caching — regions tree is fetched once per session
• Region names included — no more cryptic IDs, results show actual region names
• Drill-down support — use get-region-children to explore sub-regions
• Affinity insights — regions tool shows both top by volume and top by interest

Setup

Step 1: Create Yandex OAuth App

1. Create a Yandex ID account if you don't have one
2. Go to Yandex OAuth and create a new app
3. Under Platforms, check "Web services"
4. Under Data access, search for wordstat:api and add it
5. Click Create app
6. Note your Client ID and Client Secret

Step 2: Request API Access

Important: You must request access to the Wordstat API separately.

1. Go to Yandex Wordstat
2. Click on your profile → API access
3. Submit a request with your Client ID
4. Wait for approval (usually 1-2 business days)

Step 3: Get Your Token

export YANDEX_CLIENT_ID=your_client_id
export YANDEX_CLIENT_SECRET=your_client_secret

npx yandex-wordstat-mcp auth

This will:

1. Open your browser to Yandex authorization page
2. After you authorize, Yandex shows a code
3. Paste the code into the terminal
4. Get your access token

Step 4: Configure Claude

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "yandex-wordstat-mcp"],
      "env": {
        "YANDEX_WORDSTAT_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Code:

claude mcp add yandex-wordstat -e YANDEX_WORDSTAT_TOKEN=your_token -- npx -y yandex-wordstat-mcp

Usage Examples

Once configured, ask Claude:

Keyword Research:

• "What are the most popular search queries for 'buy iPhone' in Russia?"
• "Show me top searches containing 'real estate Moscow'"
• "What are people searching for about 'artificial intelligence'?"

Search Trends:

• "Show me the search trend for 'cryptocurrency' over the past year"
• "How has interest in 'electric cars' changed over time?"
• "Show weekly search dynamics for 'vacation Turkey'"

Regional Analysis:

• "Which regions search for 'jobs' the most?"
• "Show regional distribution for 'delivery food'"
• "Where in Russia do people search for 'ski resort' most often?"

Get Region IDs:

• "Get the Yandex Wordstat regions tree"
• "What is the region ID for Moscow?"

Online example: AI SEO-Analysis on redirekto.ru

Русский

Возможности

| Инструмент | Описание | Расход квоты | |------------|----------|--------------| | get-regions-tree | Получить топ-3 уровня иерархии регионов (глубина настраивается) | Бесплатно | | get-region-children | Детализация региона — показать дочерние регионы | Бесплатно | | top-requests | Популярные запросы с ключевым словом (за 30 дней) | 1 единица | | dynamics | Динамика поисковых запросов во времени | 2 единицы | | regions | Региональное распределение с названиями и индексом аффинитивности | 2 единицы |

Улучшения v1.2.0:

• Кэширование регионов — дерево регионов загружается один раз за сессию
• Названия регионов — результаты содержат названия, а не только ID
• Детализация — используйте get-region-children для просмотра подрегионов
• Аналитика аффинитивности — regions показывает топ по объёму и топ по интересу

Настройка

Шаг 1: Создание OAuth-приложения Яндекса

1. Создайте Яндекс ID, если у вас его нет
2. Перейдите в Яндекс OAuth и создайте новое приложение
3. В разделе Платформы выберите "Веб-сервисы"
4. В разделе Доступ к данным найдите wordstat:api и добавьте
5. Нажмите Создать приложение
6. Сохраните Client ID и Client Secret

Шаг 2: Запрос доступа к API

Важно: Необходимо отдельно запросить доступ к API Вордстата.

1. Перейдите на Яндекс Вордстат
2. Нажмите на профиль → Доступ к API
3. Отправьте заявку с вашим Client ID
4. Дождитесь подтверждения (обычно 1-2 рабочих дня)

Шаг 3: Получение токена

export YANDEX_CLIENT_ID=ваш_client_id
export YANDEX_CLIENT_SECRET=ваш_client_secret

npx yandex-wordstat-mcp auth

Команда:

1. Откроет браузер на странице авторизации Яндекса
2. После авторизации Яндекс покажет код
3. Вставьте код в терминал
4. Получите токен доступа

Шаг 4: Настройка Claude

Claude Desktop — отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "yandex-wordstat-mcp"],
      "env": {
        "YANDEX_WORDSTAT_TOKEN": "ваш_токен"
      }
    }
  }
}

Claude Code:

claude mcp add yandex-wordstat -e YANDEX_WORDSTAT_TOKEN=ваш_токен -- npx -y yandex-wordstat-mcp

Примеры использования

После настройки спросите Claude:

Исследование ключевых слов:

• "Какие самые популярные запросы по 'купить iPhone' в России?"
• "Покажи топ запросов по 'недвижимость Москва'"
• "Что ищут люди по запросу 'искусственный интеллект'?"

Динамика поиска:

• "Покажи тренд поиска 'криптовалюта' за последний год"
• "Как менялся интерес к 'электромобили' со временем?"
• "Покажи недельную динамику запросов 'отдых Турция'"

Региональный анализ:

• "В каких регионах больше всего ищут 'работа'?"
• "Покажи региональное распределение для 'доставка еды'"
• "Где в России чаще всего ищут 'горнолыжный курорт'?"

Получение ID регионов:

• "Получи дерево регионов Яндекс Вордстат"
• "Какой ID региона у Москвы?"

Онлайн пример: AI SEO-Анализ на редиректо.ru

API Quotas

Yandex Wordstat API has two quota types:

1. Total daily quota — limits total API calls per day
2. Rate limit — 10 requests per second (handled automatically)

Development

git clone https://github.com/altrr2/yandex-tools-mcp.git
cd yandex-tools-mcp/packages/yandex-wordstat-mcp
bun install

No build step needed — runs directly with Node.

bun run lint        # check
bun run lint:fix    # fix issues
bun run format      # format code

Test locally:

YANDEX_WORDSTAT_TOKEN=your-token node src/index.mjs

License

MIT © Alternex