Bukvarix 关键词搜索 MCP 服务器

Bukvarix MCP Server

MCP (Model Context Protocol) сервер для интеграции с API bukvarix.com - сервиса подбора ключевых слов для SEO.

Автор: Вечкасов Кирилл
Telegram канал: @pomogay_marketing

Описание

Этот MCP сервер предоставляет инструменты для работы с Bukvarix API, позволяя выполнять:

• Поиск ключевых слов по одной фразе
• Расширенный поиск по списку ключевых слов с исключениями
• Получение ключевых слов для домена
• Сравнение ключевых слов нескольких доменов

Установка

# Клонировать репозиторий
git clone https://github.com/VKirill/bukvarix-mcp-server.git
cd bukvarix-mcp-server

# Установить зависимости
npm install

# Собрать проект
npm run build

Использование

Переменные окружения

• BUKVARIX_API_KEY - API ключ (по умолчанию: "free" для бесплатного API)

Запуск

npm start

Интеграция с Cursor/Claude

Добавьте сервер в конфигурацию MCP (~/.cursor/mcp.json или %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json):

{
  "mcpServers": {
    "bukvarix": {
      "command": "node",
      "args": ["C:/path/to/bukvarix-mcp-server/dist/index.js"],
      "env": {
        "BUKVARIX_API_KEY": "free"
      }
    }
  }
}

Инструменты (Tools)

1. bukvarix_search_keywords

Поиск ключевых слов по одной фразе с поддержкой специального синтаксиса.

Параметры

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

Простой поиск:

{
  "query": "пластиковые окна",
  "num": 10,
  "format": "json"
}

Поиск с wildcard:

{
  "query": "строител* товары",
  "num": 50
}

Поиск с исключениями:

{
  "query": "!строительные !товары"
}

Только количество результатов:

{
  "query": "окна",
  "result_count": true
}

Возвращаемые данные (JSON формат)

{
  "data": [
    [
      "пластиковые окна",
      2,
      16,
      8343275,
      9632
    ]
  ]
}

Где:

• [0] - ключевое слово/фраза
• [1] - количество слов во фразе
• [2] - количество символов во фразе
• [3] - широкая частотность (worldwide)
• [4] - точная частотность (worldwide)

2. bukvarix_search_keywords_batch

Расширенный поиск по списку ключевых слов с поддержкой исключений.

Параметры

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

Поиск по нескольким фразам:

{
  "queries": ["окна", "двери", "балконы"],
  "num": 20,
  "format": "json"
}

Поиск с исключениями:

{
  "queries": ["окна"],
  "exclusions": ["деревянные", "старые"],
  "num": 50
}

Ограничения бесплатного API

• Максимум 100 запросов в queries
• Максимум 250 исключений в exclusions
• При превышении лимита лишние строки игнорируются

3. bukvarix_get_domain_keywords

Получение ключевых слов для домена или поддомена с позициями в поисковой выдаче.

Параметры

Регионы поисковых машин

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

Базовый запрос:

{
  "domain": "wildberries.ru",
  "num": 50,
  "format": "json"
}

С указанием региона:

{
  "domain": "wildberries.ru",
  "region": "spb",
  "num": 100
}

Поддомен:

{
  "domain": "shop.example.com"
}

Только количество:

{
  "domain": "example.com",
  "result_count": true
}

Возвращаемые данные (JSON формат)

{
  "data": [
    [
      "вайлдберриз",
      8000000,
      1,
      11,
      10099697,
      5143150,
      1
    ]
  ]
}

Где:

• [0] - ключевое слово
• [1] - количество слов во фразе
• [2] - количество символов во фразе
• [3] - количество результатов в поисковой машине
• [4] - широкая частотность (worldwide)
• [5] - точная частотность (worldwide)
• [6] - позиция в поисковой выдаче

4. bukvarix_compare_domains

Сравнение ключевых слов между несколькими доменами.

Параметры

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

Сравнение двух доменов (общие ключевые слова):

{
  "domains": ["wildberries.ru", "lamoda.ru"],
  "comparison_type": "intersect",
  "num": 50
}

Уникальные ключевые слова первого домена:

{
  "domains": ["wildberries.ru", "lamoda.ru"],
  "comparison_type": "domain1_uniq",
  "region": "rus"
}

Сравнение нескольких доменов:

{
  "domains": ["wildberries.ru", "lamoda.ru", "quelle.ru"],
  "num": 100
}

Ограничения

• Для бесплатного API: максимум 10 доменов
• comparison_type работает только для сравнения 2 доменов
• При сравнении 3+ доменов всегда возвращаются общие ключевые слова

Форматы данных

Все инструменты поддерживают следующие форматы вывода:

JSON (по умолчанию)

Структурированные данные в формате массива объектов или массивов.

Пример:

{
  "data": [
    ["ключевое слово", 2, 16, 1000, 500]
  ]
}

TXT

Простой список ключевых слов, каждое на новой строке.

Пример:

пластиковые окна
окна пвх
окна москва

CSV

Таблица с разделителем точка с запятой, текстовые значения в кавычках.

Пример:

Ключевое слово;Слов;Символов;Широкая частотность;Точная частотность
"пластиковые окна";2;16;1000;500

TSV

Таблица с разделителем табуляция, текстовые значения без кавычек.

Пример:

Ключевое слово	Слов	Символов	Широкая частотность	Точная частотность
пластиковые окна	2	16	1000	500

Обработка ошибок

Сервер обрабатывает следующие HTTP коды ошибок:

Ограничения бесплатного API

• Поиск ключевых слов: до 100 запросов в batch search
• Исключения: до 250 строк в batch search
• Сравнение доменов: до 10 доменов
• Количество результатов: максимум 1,000,000 строк в отчете
• Rate limiting: ограничения по частоте запросов (при ошибке 429 сделайте паузу)

Специальный синтаксис запросов

Bukvarix API поддерживает специальные символы в запросах:

• * - wildcard (подстановка). Пример: строител* найдет "строительные", "строительство", "строитель"
• ! - исключение. Пример: !строительные !товары исключит фразы содержащие эти слова
• ~ - синонимы (в некоторых случаях)

Важно: Специальные символы должны передаваться в перекодированном виде (percent-encoding). Сервер автоматически обрабатывает кодирование.

API Endpoints

Сервер использует следующие endpoints Bukvarix API:

• GET /v1/keywords/ - простой поиск ключевых слов
• POST /v1/mkeywords/ - расширенный поиск по списку
• GET /v1/site/ - ключевые слова домена
• GET /v1/site_cmp/ - сравнение двух доменов
• POST /v1/site_mcmp/ - сравнение нескольких доменов

Разработка

# Разработка с автоперезагрузкой
npm run dev

# Сборка проекта
npm run build

# Очистка dist
npm run clean

Технологии

• TypeScript - типизированный JavaScript
• MCP SDK - Model Context Protocol SDK
• Zod - валидация схем данных
• Axios - HTTP клиент для запросов к API

Тестирование

Проект включает тестовые скрипты для проверки всех инструментов:

# Запуск всех тестов
node test-tools.js

# Тест конкретного инструмента
node test-api-client.js

Лицензия

MIT

Автор

Вечкасов Кирилл

• Telegram канал: @pomogay_marketing
• Создано для интеграции Bukvarix API с MCP протоколом

Полезные ссылки

• Bukvarix API Документация
• MCP Protocol
• TypeScript SDK