yandex-wordstat-mcp

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

English | Русский

English

Features

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

Русский

Возможности

Настройка

Шаг 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