Just-Magic MCP Server

An MCP server for working with the API of the Just-Magic.org service — a platform for SEO automation and semantic analysis.

Features

The server provides the following tools:

📊 Account information and task management

• justmagic_info — account information (tariff, balance, expiry date)

• justmagic_list_tasks — a list of the user's tasks

• justmagic_get_task — retrieving a task's results

🔍 Clustering and analysis

• justmagic_cluster — clustering the semantic core by Yandex/Google top results

• justmagic_text_analyzer — analysis of page text optimization

• justmagic_thematic_classifier — thematic classification of queries

📝 LSI and texts

• justmagic_aquarelle — LSI analysis of text for topical relevance to a query

• justmagic_aquarelle_generator — generating a list of LSI words for writing text

📈 Frequency and suggestions

• justmagic_wordstat_frequency — collecting frequency data from Yandex.Wordstat

• justmagic_wordstat_suggestions — collecting Wordstat suggestions

• justmagic_suggestions_parser — parsing search suggestions with iterations

🔗 Distribution and expansion

• justmagic_markers_online — distributing queries across site pages

• justmagic_expand_semantics — expanding the semantic core

• justmagic_regex_search — searching the keyword database with a regular expression

Requirements

• Python 3.10+

• A Just-Magic.org account with the "Эцилопп" tariff or higher (for API access)

Installation

Unpack the archive (or clone the repository) to a convenient location, e.g. ~/code/just-magic-mcp, and create a virtual environment with the dependencies:

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

⚠️ Important: the mcp library version 1.x is required — with mcp 2.0 the server will not start. The command above installs the correct version.

Check that everything is set up correctly:

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

Configuration

1. Get an API key

Sign in to the Just-Magic personal account and copy your API key.

The key is passed to the server via the JUSTMAGIC_API_KEY environment variable. There's no need to export it globally in the shell — it goes into the config of the client that launches the server (Claude Desktop or Hermes), see below.

2a. Connecting Claude Desktop

Add the following to the Claude Desktop config file:

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_ключ"
      }
    }
  }
}

Replace /ПОЛНЫЙ/ПУТЬ/К/ with the real path (for example /Users/ivan/code/) and put your API key in place of ваш_api_ключ. Then restart Claude Desktop.

2b. Connecting Hermes

Method 1 — interactively via CLI:

hermes mcp add

Answer the wizard's prompts: transport — stdio, command — the full path to venv/bin/python, args — the full path to server.py, environment variable — JUSTMAGIC_API_KEY with your key as its value.

Method 2 — manually. Add a top-level block to ~/.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}

And put the key itself in the ~/.hermes/.env file (create it if it doesn't exist):

JUSTMAGIC_API_KEY=ваш_api_ключ

The ${JUSTMAGIC_API_KEY} reference in the config is substituted from .env automatically — so the key is not stored in config.yaml. You can also write the key directly into env: in config.yaml, but the .env variant is cleaner.

After editing the config, start a new Hermes session so the tools are loaded. To check the connection: hermes mcp list and hermes mcp test just-magic.

Additional environment variables (optional)

• JUSTMAGIC_DB_PATH — path to a local SQLite database for saving results (default: ~/justmagic_results.db).

Usage examples

Query clustering

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

Page text analysis

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

Collecting LSI words

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

Checking the cost of a task

All tools support the just_ask: true parameter — when it's set, the task isn't executed and only its cost is calculated.

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

Asynchronous operation

Just-Magic.org uses an asynchronous task execution model:

1. You submit a task and get a tid (task ID)

2. You check the status with justmagic_get_task

3. When the task is ready, you receive the result

Recommended check interval: 30+ seconds.

Yandex region codes

A few popular regions:

Full list: Yandex Help

License

MIT

Links

• Just-Magic.org

• API Documentation

• Telegram channel

• MCP Specification