Yandex Wordstat MCP

# yandex-wordstat-mcp MCP server for [Yandex Wordstat API](https://wordstat.yandex.com/) — keyword research and search trend analysis for the Russian market. [](https://www.npmjs.com/package/yandex-wordstat-mcp) [](https://opensource.org/licenses/MIT) [English](#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](https://passport.yandex.com/) if you don't have one 2. Go to [Yandex OAuth](https://oauth.yandex.com/) 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](https://wordstat.yandex.com/) 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 ```bash 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): ```json { "mcpServers": { "yandex-wordstat": { "command": "npx", "args": ["-y", "yandex-wordstat-mcp"], "env": { "YANDEX_WORDSTAT_TOKEN": "your_token_here" } } } } ``` **Claude Code:** ```bash 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](https://passport.yandex.com/), если у вас его нет 2. Перейдите в [Яндекс OAuth](https://oauth.yandex.com/) и создайте новое приложение 3. В разделе **Платформы** выберите "Веб-сервисы" 4. В разделе **Доступ к данным** найдите `wordstat:api` и добавьте 5. Нажмите **Создать приложение** 6. Сохраните **Client ID** и **Client Secret** #### Шаг 2: Запрос доступа к API **Важно:** Необходимо отдельно запросить доступ к API Вордстата. 1. Перейдите на [Яндекс Вордстат](https://wordstat.yandex.com/) 2. Нажмите на профиль → **Доступ к API** 3. Отправьте заявку с вашим Client ID 4. Дождитесь подтверждения (обычно 1-2 рабочих дня) #### Шаг 3: Получение токена ```bash 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): ```json { "mcpServers": { "yandex-wordstat": { "command": "npx", "args": ["-y", "yandex-wordstat-mcp"], "env": { "YANDEX_WORDSTAT_TOKEN": "ваш_токен" } } } } ``` **Claude Code:** ```bash 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 ```bash git clone https://github.com/iichat/yandex-wordstat-mcp.git cd yandex-wordstat-mcp bun install ``` No build step needed — runs directly with Node. ```bash bun run lint # check bun run lint:fix # fix issues bun run format # format code ``` Test locally: ```bash YANDEX_WORDSTAT_TOKEN=your-token node src/index.mjs ``` --- ## License MIT © Alternex