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 all supported regions with IDs	Free
top-requests	Popular queries containing a keyword (last 30 days)	1 unit
dynamics	Search volume trends over time	2 units
regions	Regional distribution of search volume	2 units

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?"

---

Русский

Возможности

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

Настройка

Шаг 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 региона у Москвы?"

---

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/iichat/yandex-wordstat-mcp.git
cd 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