Just-Magic MCP Server

MCP сервер для работы с API сервиса Just-Magic.org — платформы для SEO-автоматизации и работы с семантикой.

Возможности

Сервер предоставляет следующие инструменты:

📊 Информация и управление задачами

• justmagic_info — информация об аккаунте (тариф, баланс, срок действия)
• justmagic_list_tasks — список задач пользователя
• justmagic_get_task — получение результатов задачи

🔍 Кластеризация и анализ

• justmagic_cluster — кластеризация семантического ядра по топам Яндекс/Google
• justmagic_text_analyzer — анализ текстовой оптимизации страниц
• justmagic_thematic_classifier — тематическая классификация запросов

📝 LSI и тексты

• justmagic_aquarelle — LSI-анализ текста на тематичность запросу
• justmagic_aquarelle_generator — генерация списка LSI-слов для написания текста

📈 Частотность и подсказки

• justmagic_wordstat_frequency — сбор частотности из Яндекс.Wordstat
• justmagic_wordstat_suggestions — сбор подсказок Wordstat
• justmagic_suggestions_parser — парсер поисковых подсказок с итерациями

🔗 Распределение и расширение

• justmagic_markers_online — распределение запросов по страницам сайта
• justmagic_expand_semantics — расширение семантического ядра
• justmagic_regex_search — поиск в базе ключевых слов по регулярному выражению

Требования

• Python 3.10+
• Аккаунт Just-Magic.org с тарифом "Эцилопп" или выше (для доступа к API)

Установка

Распакуйте архив (или склонируйте репозиторий) в удобное место, например ~/code/just-magic-mcp, и создайте виртуальное окружение с зависимостями:

cd ~/code/just-magic-mcp
python3 -m venv venv
./venv/bin/pip install "mcp>=1.0.0,<2" "httpx>=0.27.0"

⚠️ Важно: нужна библиотека mcp версии 1.x — с mcp 2.0 сервер не запустится. Команда выше ставит правильную версию.

Проверка, что всё собралось:

./venv/bin/python -c "import server; print('OK')"

Настройка

1. Получите API-ключ

Войдите в личный кабинет Just-Magic и скопируйте ваш API-ключ.

Ключ передаётся серверу через переменную окружения JUSTMAGIC_API_KEY. Её не нужно экспортировать глобально в шелле — она задаётся в конфиге того клиента, который запускает сервер (Claude Desktop или Hermes), см. ниже.

2а. Подключение к Claude Desktop

Добавьте в файл конфигурации Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "just-magic": {
      "command": "/ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/venv/bin/python",
      "args": ["/ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/server.py"],
      "env": {
        "JUSTMAGIC_API_KEY": "ваш_api_ключ"
      }
    }
  }
}

Замените /ПОЛНЫЙ/ПУТЬ/К/ на реальный путь (например /Users/ivan/code/) и вставьте свой API-ключ вместо ваш_api_ключ. После этого перезапустите Claude Desktop.

2б. Подключение к Hermes

Способ 1 — интерактивно через CLI:

hermes mcp add

На вопросы мастера ответьте: transport — stdio, command — полный путь к venv/bin/python, args — полный путь к server.py, переменная окружения — JUSTMAGIC_API_KEY со значением вашего ключа.

Способ 2 — вручную. Добавьте в ~/.hermes/config.yaml блок верхнего уровня:

mcp_servers:
  just-magic:
    command: /ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/venv/bin/python
    args:
      - /ПОЛНЫЙ/ПУТЬ/К/just-magic-mcp/server.py
    env:
      JUSTMAGIC_API_KEY: ${JUSTMAGIC_API_KEY}

А сам ключ положите в файл ~/.hermes/.env (создайте, если его нет):

JUSTMAGIC_API_KEY=ваш_api_ключ

Ссылка ${JUSTMAGIC_API_KEY} в конфиге подставится из .env автоматически — так ключ не хранится в config.yaml. Можно и вписать ключ прямо в env: в config.yaml, но вариант с .env аккуратнее.

После правки конфига начните новую сессию Hermes, чтобы инструменты подгрузились. Проверить подключение: hermes mcp list и hermes mcp test just-magic.

Дополнительные переменные окружения (необязательно)

• JUSTMAGIC_DB_PATH — путь к локальной SQLite-базе для сохранения результатов (по умолчанию ~/justmagic_results.db).

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

Кластеризация запросов

Кластеризуй эти запросы для Москвы:
- купить ноутбук
- ноутбук цена
- ноутбук для работы
- ноутбук игровой

Анализ текста страницы

Проанализируй текстовую оптимизацию страницы https://example.com/notebook 
по запросам: купить ноутбук, ноутбук недорого

Сбор LSI-слов

Сгенерируй список LSI-слов для написания текста про "ремонт квартир"

Проверка стоимости задачи

Все инструменты поддерживают параметр just_ask: true — при его установке задача не выполняется, а только рассчитывается её стоимость.

Сколько будет стоить кластеризация 1000 запросов?

Асинхронная работа

Just-Magic.org использует асинхронную модель выполнения задач:

1. Вы ставите задачу → получаете tid (ID задачи)
2. Проверяете статус через justmagic_get_task
3. Когда задача готова, получаете результат

Рекомендуемый интервал проверки: 30+ секунд.

Коды регионов Яндекса

Некоторые популярные регионы:

Код	Регион
213	Москва
2	Санкт-Петербург
54	Екатеринбург
43	Казань
47	Нижний Новгород
65	Новосибирск
11119	Вся Россия

Полный список: Яндекс.Помощь

Лицензия

MIT

Ссылки

• Just-Magic.org
• Документация API
• Telegram-канал
• MCP Specification