Just-Magic MCP Server

Servidor MCP para trabajar con la API del servicio Just-Magic.org — una plataforma para la automatización de SEO y el trabajo con semántica.

Características

El servidor proporciona las siguientes herramientas:

📊 Información y gestión de tareas

• justmagic_info — información de la cuenta (tarifa, saldo, fecha de vencimiento)

• justmagic_list_tasks — lista de tareas del usuario

• justmagic_get_task — obtención de los resultados de la tarea

🔍 Clustering y análisis

• justmagic_cluster — clustering del núcleo semántico por los top de Яндекс/Google

• justmagic_text_analyzer — análisis de la optimización textual de las páginas

• justmagic_thematic_classifier — clasificación temática de las consultas

📝 LSI y textos

• justmagic_aquarelle — análisis LSI del texto para comprobar su pertinencia temática con la consulta

• justmagic_aquarelle_generator — generación de una lista de palabras LSI para redactar el texto

📈 Frecuencias y sugerencias

• justmagic_wordstat_frequency — recopilación de frecuencias desde Яндекс.Wordstat

• justmagic_wordstat_suggestions — recopilación de sugerencias de Wordstat

• justmagic_suggestions_parser — parser de sugerencias de búsqueda con iteraciones

🔗 Distribución y ampliación

• justmagic_markers_online — distribución de las consultas por las páginas del sitio

• justmagic_expand_semantics — ampliación del núcleo semántico

• justmagic_regex_search — búsqueda en la base de palabras clave mediante una expresión regular

Requisitos

• Python 3.10+

• Cuenta de Just-Magic.org con la tarifa «Эцилопп» o superior (para acceder a la API)

Instalación

Descomprima el archivo (o clone el repositorio) en un lugar adecuado, por ejemplo ~/code/just-magic-mcp, y cree un entorno virtual con las dependencias:

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

⚠️ Importante: se necesita la librería mcp versión 1.x — con mcp 2.0 el servidor no se iniciará. El comando anterior instala la versión correcta.

Comprobación de que todo quedó instalado correctamente:

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

Configuración

1. Obtenga la clave de API

Entre en su cuenta personal de Just-Magic y copie su clave de API.

La clave se pasa al servidor mediante la variable de entorno JUSTMAGIC_API_KEY. No hace falta exportarla globalmente en el shell; se define en la configuración del cliente que ejecuta el servidor (Claude Desktop o Hermes), ver más abajo.

2а. Conexión a Claude Desktop

Añada al archivo de configuración de 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_ключ"
      }
    }
  }
}

Sustituya /ПОЛНЫЙ/ПУТЬ/К/ por la ruta real (por ejemplo /Users/ivan/code/) e introduzca su clave de API en lugar de ваш_api_ключ. Después reinicie Claude Desktop.

2б. Conexión a Hermes

Método 1 — interactivo a través de CLI:

hermes mcp add

Responda a las preguntas del asistente: transport — stdio, command — ruta completa a venv/bin/python, args — ruta completa a server.py, variable de entorno — JUSTMAGIC_API_KEY con el valor de su clave.

Método 2 — manualmente. Agregue en ~/.hermes/config.yaml un bloque de nivel superior:

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

Y la clave, colóquela en el archivo ~/.hermes/.env (créelo si no existe):

JUSTMAGIC_API_KEY=ваш_api_ключ

La referencia ${JUSTMAGIC_API_KEY} en la configuración se sustituirá desde .env automáticamente; así la clave no se guarda en config.yaml. También se puede escribir la clave directamente en env: en config.yaml, pero la opción con .env es más ordenada.

Después de editar la configuración, inicie una nueva sesión de Hermes para que las herramientas se carguen. Para comprobar la conexión: hermes mcp list y hermes mcp test just-magic.

Variables de entorno adicionales (opcional)

• JUSTMAGIC_DB_PATH — ruta a la base de datos local SQLite para guardar los resultados (por defecto ~/justmagic_results.db).

Ejemplos de uso

Clustering de consultas

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

Análisis del texto de la página

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

Recopilación de palabras LSI

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

Comprobación del coste de la tarea

Todas las herramientas soportan el parámetro just_ask: true: si se establece, la tarea no se ejecuta y solo se calcula su coste.

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

Trabajo asíncrono

Just-Magic.org utiliza un modelo asíncrono de ejecución de tareas:

1. Usted envía la tarea → recibe un tid (ID de la tarea)

2. Comprueba el estado mediante justmagic_get_task

3. Cuando la tarea esté lista, obtiene el resultado

Intervalo de comprobación recomendado: 30+ segundos.

Códigos de regiones de Яндекс

Algunos de los más populares:

Lista completa: Яндекс.Помощь

Licencia

MIT

Enlaces

• Just-Magic.org

• Документация API

• Telegram-канал

• MCP Specification