Xmlriver Mcp

xmlriver-mcp

XMLRiver 用 MCP サーバー — XML API 経由で Google/Yandex の SERP を解析し、Yandex Wordstat のキーワード頻度データを取得します。

mcp-name: io.github.artgas1/xmlriver-mcp

できること

Claude / Cursor / Windsurf から次の機能を直接利用できます。

• Google SERP の解析（オーガニック検索結果、広告、FAQ、ナレッジグラフ、AI Overview）。任意の国・地域・デバイスに対応します
• Yandex SERP の解析（ロシア語圏市場向け。主な用途です）
• Yandex Wordstat のキーワード頻度、履歴、類似クエリ（Yandex のキーワード検索ボリュームツール）
• インデックス登録の確認 — この URL は Google/Yandex のインデックスに登録されていますか？
• アカウント操作 — 残高、料金プラン、リクエスト 1,000 件あたりの料金

XMLRiver 向け初の MCP で、ロシア語圏の SEO 調査と Yandex を考慮した分析を補完します。従量課金制（Basic 料金プランでは 1,000 リクエストあたり約 25 ₽）です。

デモ

Claude は wordstat_query を呼び出して、Yandex から実際の頻度データを取得・解析します。同じ手順で google_search、yandex_search、インデックス登録の確認、アカウント操作も利用できます。

クイックスタート

uvx xmlriver-mcp

設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "xmlriver": {
      "command": "uvx",
      "args": ["xmlriver-mcp"],
      "env": {
        "XMLRIVER_USER": "<your_numeric_user_id>",
        "XMLRIVER_KEY": "<your_40_char_hex_key>"
      }
    }
  }
}

Claude Code

プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "xmlriver": {
      "command": "uvx",
      "args": ["xmlriver-mcp"],
      "env": {
        "XMLRIVER_USER": "<your_numeric_user_id>",
        "XMLRIVER_KEY": "<your_40_char_hex_key>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）を編集します。

{
  "mcpServers": {
    "xmlriver": {
      "command": "uvx",
      "args": ["xmlriver-mcp"],
      "env": {
        "XMLRIVER_USER": "<your_numeric_user_id>",
        "XMLRIVER_KEY": "<your_40_char_hex_key>"
      }
    }
  }
}

ツール

ツール	機能
google_search	Google SERP を解析します。クエリに対し、国、言語、デバイス、ページ、日付フィルター、追加ブロック（広告、FAQ、ナレッジグラフ、AI Overview）を指定できます
yandex_search	Yandex SERP を解析します。地域、言語、デバイス、ページ、日付フィルター、追加ブロックを指定できます
yandex_search_api_v2	XMLRiver 経由の Yandex Search API v2（公式）を利用し、より整理された構造化出力を取得します
wordstat_query	Yandex Wordstat のキーワード頻度と類似クエリ、または月別／週別／日別の需要動向を取得します
search_suggestions	Google または Yandex の検索ボックスのオートコンプリートを取得します。1 回の呼び出しで 1〜50 件のフレーズを指定できます。Wordstat の頻度データがまったくないロングテールの表現も見つけられます
google_maps_search	指定した座標周辺の Google Maps の場所を検索します（ズームと座標が必須）。⚠️ 下記の注意事項をご覧ください
check_url_indexed	URL が Google または Yandex にインデックスされているか確認します
get_balance	XMLRiver の現在の残高をルーブルで取得します
get_tariff	XMLRiver の現在の料金プラン名（Basic / Pro / Mega / Giga）を取得します
get_tariff_expire	料金プランの有効期限（前払いプランの場合）を取得します
get_cost	指定したエンジン（google / yandex / yaxml / wordstat）のリクエスト 1000 件あたりの料金を取得します

すべてのツールは読み取り専用です（readOnlyHint: true が設定されています）。破壊的な操作はありません。

⚠️ google_maps_search は実際の応答で検証されていません。 実装中（2026-08-04）に、すべての setab=maps リクエストが code 500 を返しました。意図的に無効なリクエストも同様で、本来は code 108 を返すはずでした。同じ時間帯に通常の Google 検索と Yandex 検索は機能していたため、このモードはサービス側で利用できないようです。リクエスト形式と応答の解析はドキュメントに沿っており、ユニットテストでも確認していますが、どちらも実際の応答による検証が必要です。

意図的にラップしていないもの： raw=page（HTML ページ全体を返します。解析を迂回し、モデルのコンテキストに数メガバイトのデータを返します）と遅延応答モード（delayed / req_id）です。MCP 呼び出しは同期処理のため、呼び出し元がポーリングする必要のあるリクエスト ID は実用的な使い道がありません。

認証

1. https://xmlriver.com で登録します
2. 残高をチャージします（開始時の最低額は約 100 ₽ です）
3. ダッシュボードから user（数値 ID）と key（40 文字の 16 進数文字列）を取得します
4. MCP クライアントの設定で、環境変数 XMLRIVER_USER と XMLRIVER_KEY を設定します

セキュリティに関する注意： XMLRiver API は HTTP のみ（HTTPS ではありません）に対応しています。キーが漏洩した場合は、ダッシュボードからキーを変更できます。

料金の概要

料金プラン	設定	Google / Yandex / Wordstat	Yandex Search API v2
Basic	従量課金	25 ₽ / 1k	25 ₽ / 1k
Pro	5000 ₽/mo	20 ₽ / 1k	24 ₽ / 1k
Mega	15000 ₽/mo	15 ₽ / 1k	23 ₽ / 1k
Giga	50000 ₽/mo	12 ₽ / 1k	22 ₽ / 1k

一括操作の前に get_balance と get_cost を使って支出を確認してください。

よくあるユースケース

• SEO の順位追跡 — yandex_search(query="...", region=213) で自社や競合の順位を確認します
• キーワード調査 — wordstat_query(query="купить iphone", history_period="monthly") で需要を検証し、季節性を確認します
• 強調スニペットの調査 — google_search(additional_blocks="faqsnippet,knowledge_graph,zeroposition") で、回答ボックスに表示される情報を確認します
• ロングテールの発見 — 接頭辞を変えながら（シード語とアルファベットの各文字）search_suggestions(phrases=[...]) を使うと、Wordstat では報告されない表現を見つけられます
• インデックス登録の監視 — 公開後に check_url_indexed(url="https://your-site.com/new-page") で確認します
• 地域間の比較 — 同じクエリで region / country を変えて Yandex / Google を検索し、地域による違いを確認します

ローカル開発

git clone https://github.com/artgas1/xmlriver-mcp
cd xmlriver-mcp
uv sync --all-extras

# Run unit tests (no API key needed)
uv run pytest tests/unit -v

# Run integration tests (requires XMLRIVER_USER / XMLRIVER_KEY)
XMLRIVER_USER=... XMLRIVER_KEY=... uv run pytest tests/integration -v -m integration

# MCP Inspector — interactive
XMLRIVER_USER=... XMLRIVER_KEY=... npx @modelcontextprotocol/inspector uv run python -m xmlriver_mcp.server

# MCP Inspector — CLI smoke test (list tools)
npx @modelcontextprotocol/inspector --cli "uv run python -m xmlriver_mcp.server" --method tools/list

アーキテクチャ

• 技術スタック： Python 3.10+ / FastMCP / httpx / tenacity / pydantic
• トランスポート： stdio（デフォルト）
• 外部 SDK への依存なし — httpx による REST への直接アクセスとカスタム XML パーサーを使用します
• 再試行戦略： ネットワークエラー時に指数バックオフで 3 回試行します（HTTP 4xx の場合は再試行しません）
• ログ： stderr のみ（stdio プロトコルでは、JSON-RPC 用に stdout が必要です）

ライセンス

MIT

貢献

プルリクエストを歓迎します。大規模な変更を行う場合は、まず Issue を作成してください。

謝辞

• XMLRiver — 基盤となる API を提供していただきました
• Anthropic MCP — プロトコルを提供していただきました