Just-Magic MCP Server

MCP 服务器，用于与 Just-Magic.org 服务的 API 对接——这是一个专注于 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 传递给服务器。不需要在 shell 中全局导出它——它会在启动服务器的客户端（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 秒以上。

Яндекс 的区域代码

一些热门区域：

完整列表：Яндекс.Помощь

许可证

MIT

相关链接

• Just-Magic.org

• API 文档

• Telegram 频道

• MCP Specification