Just-Magic MCP Server

Just-Magic.org サービスの API を操作するための MCP サーバー — SEO 自動化とセマンティクス処理のためのプラットフォームです。

機能

サーバーは以下のツールを提供します。

📊 情報とタスク管理

• justmagic_info — アカウント情報（プラン、残高、有効期限）

• justmagic_list_tasks — ユーザーのタスク一覧

• justmagic_get_task — タスク結果の取得

🔍 クラスタリングと分析

• justmagic_cluster — Яндекс/Googol の検索上位に基づくセマンティックコアのクラスタリング

• 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 にキーが保存されずに済みます。config.yaml の env: に直接キーを書くこともできますが、.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秒以上。

ЯRegion（Регионы Яnдекс）

人気のある地域のいくつか:

完全なリスト: Яндекс。Помощь

ライセンス

MIT

リンク

• Just-Magic.org

• API ドキュメント

• Telegram チャンネル

• MCP Specification