Just-Magic MCP Server

MCP 서버는 SEO 자동화 및 시맨틱 작업을 위한 플랫폼인 Just-Magic.org API와 연동하는 서버입니다.

기능

서버는 다음과 같은 도구를 제공합니다:

📊 정보 및 작업 관리

• 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+

• API 접근을 위해 "Эцилопп" 이상 요금제가 있는 Just-Magic.org 계정

설치

아카이브 압축을 풀거나(또는 저장소를 클론) ~/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_ключ

config.yaml 안의 ${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초 이상.

Яндекс 지역 코드

주요 지역:

전체 목록: Яндекс.Помощь

Лицензия

MIT

Ссылки

• Just-Magic.org

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

• Telegram-канал

• MCP Specification