Skip to main content
Glama
xmlriver-mcp

xmlriver-mcp

xmlriver-mcp

MCP server for XMLRiver — Google/Yandex SERP parsing and Yandex Wordstat keyword frequency data via XML API.

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

Add to Cursor Add to VS Code Add to Claude Desktop

PyPI Downloads License: MIT Python 3.10+

What it does

Gives Claude / Cursor / Windsurf direct access to:

  • Google SERP parsing (organic, ads, FAQ, knowledge graph, AI Overview) for any country / region / device

  • Yandex SERP parsing (Russian-speaking markets — primary use case)

  • Yandex Wordstat keyword frequency, history, similar queries (Yandex's keyword volume tool)

  • Indexing check — is this URL in Google/Yandex index?

  • Account ops — balance, tariff, cost per 1k requests

First MCP for XMLRiver — fills a gap for Russian SEO research and Yandex-aware analysis. Pay-as-you-go (~25 ₽ / 1000 requests on Basic tariff).

Related MCP server: yandex-mcp

Demo

Claude queries wordstat_query and parses real frequency data from Yandex. Same flow works for google_search, yandex_search, indexing checks, and account ops.

Quickstart

uvx xmlriver-mcp

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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

Add to project .mcp.json:

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

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

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

Tools

Tool

What it does

google_search

Parse Google SERP for a query — country, language, device, page, date filter, extra blocks (ads, FAQ, knowledge graph, AI Overview)

yandex_search

Parse Yandex SERP — region, language, device, page, date filter, extra blocks

yandex_search_api_v2

Yandex Search API v2 (official) via XMLRiver — cleaner structured output

wordstat_query

Yandex Wordstat keyword frequency + similar queries, or demand dynamics by month/week/day

search_suggestions

Search-box autocomplete from Google or Yandex, 1–50 phrases per call. Surfaces long-tail phrasings that carry no Wordstat frequency at all

google_maps_search

Google Maps places around a coordinate (zoom + coords required). ⚠️ See caveat below

check_url_indexed

Check if URL is indexed in Google or Yandex

get_balance

Current XMLRiver balance in rubles

get_tariff

Current XMLRiver tariff name (Basic / Pro / Mega / Giga)

get_tariff_expire

Tariff expiration date (for prepay tariffs)

get_cost

Cost per 1000 requests for a given engine (google / yandex / yaxml / wordstat)

All tools are read-only (annotated with readOnlyHint: true). No destructive operations.

⚠️ google_maps_search is unverified against a live response. Every setab=maps request answered code 500 while it was written (2026-08-04), including a deliberately invalid one that should have returned code 108 — plain Google and Yandex searches worked in the same minutes, so the mode appears unavailable service-side. The request shape and response parsing follow the documentation and are covered by unit tests; both still need a live check.

Deliberately not wrapped: raw=page (returns the full HTML page — bypasses parsing and returns megabytes into the model's context) and the deferred-response mode (delayed / req_id) — an MCP call is synchronous, so a request id the caller must poll for has nowhere useful to go.

Authentication

  1. Register at https://xmlriver.com

  2. Top up balance (minimum ~100 ₽ to start)

  3. Get your user (numeric ID) and key (40-char hex) from the dashboard

  4. Set XMLRIVER_USER and XMLRIVER_KEY env vars in your MCP client config

Security note: XMLRiver API is HTTP-only (not HTTPS). The key is rotatable from the dashboard if compromised.

Pricing context

Tariff

Setup

Google / Yandex / Wordstat

Yandex Search API v2

Basic

Pay-as-you-go

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

Use get_balance and get_cost to monitor spend before bulk operations.

Common use cases

  • SEO position tracking — yandex_search(query="...", region=213) for own/competitor ranking

  • Keyword research — wordstat_query(query="купить iphone", history_period="monthly") for demand validation + seasonality

  • Featured snippet hunting — google_search(additional_blocks="faqsnippet,knowledge_graph,zeroposition") to see what owns the answer box

  • Long-tail discovery — search_suggestions(phrases=[...]) with a prefix sweep (seed + each letter of the alphabet) pulls phrasings Wordstat never reports

  • Indexation monitoring — check_url_indexed(url="https://your-site.com/new-page") after publishing

  • Cross-region comparison — same query, different region/country for Yandex/Google to see geographic variance

Local development

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

Architecture

  • Stack: Python 3.10+ / FastMCP / httpx / tenacity / pydantic

  • Transport: stdio (default)

  • No external SDK dependency — direct REST via httpx + custom XML parser

  • Retry strategy: 3 attempts with exponential backoff on network errors (not on HTTP 4xx)

  • Logging: stderr only (stdio protocol requires stdout for JSON-RPC)

License

MIT

Contributing

PRs welcome. Open an issue first for substantial changes.

Acknowledgements

Available Tools

9 tools
check_url_indexedA
Read-onlyIdempotent

Check if a URL is indexed in Google or Yandex.

Internally uses url:<URL> operator with inindex=1 flag to xmlriver (forces fresh index check, not cache).

Use this for: SEO audits, indexation monitoring, "did Google find my new page?".

Returns: Dict with: - url — checked URL - search_engine - indexed — bool - details — full search results if indexed (with title, snippet, position)

Inputs: url (required), search_engine, country. Returns: object

get_balanceA
Read-onlyIdempotent

Get current XMLRiver account balance in rubles (₽).

Use this to check funds before bulk operations or to monitor spending.

Returns: Dict with balance_rub (float) or isError on failure.

Examples: get_balance() → {"balance_rub": 1234.56}

Inputs: no named parameters. Returns: object

get_costA
Read-onlyIdempotent

Get cost per 1000 requests for a given engine, in rubles (₽).

Use this to estimate spend for a planned bulk operation. Cost depends on current tariff — see get_tariff for the tariff name.

Returns: Dict with engine, cost_per_1k_rub or isError.

Examples: get_cost(engine="google") → {"engine": "google", "cost_per_1k_rub": 25.0}

Inputs: engine (required). Returns: object

get_tariffA
Read-onlyIdempotent

Get current XMLRiver tariff name.

Tariffs:

  • 'Basic' — pay-as-you-go, no prepay, 25 ₽ per 1k requests

  • 'Pro' — 5000 ₽/mo prepay, 20 ₽ per 1k

  • 'Mega' — 15000 ₽/mo prepay, 15 ₽ per 1k

  • 'Giga' — 50000 ₽/mo prepay, 12 ₽ per 1k

Returns: Dict with tariff (str) or isError.

Inputs: no named parameters. Returns: object

get_tariff_expireA
Read-onlyIdempotent

Get expiration date for prepay tariff (Pro/Mega/Giga).

Returns 'never' or date for Basic tariff (no expiry).

Returns: Dict with expires_at (str) or isError.

Inputs: no named parameters. Returns: object

wordstat_queryA
Read-onlyIdempotent

Get Yandex Wordstat frequency for a keyword phrase.

Use this for: keyword research, demand validation, seasonality analysis, long-tail discovery. Russian/Yandex-speaking markets — this is Yandex's equivalent of Google Keyword Planner.

Do NOT use for: Google volume (Wordstat is Yandex-only — for Google use Google Keyword Planner or third-party tools).

Returns: Dict with: - query (echoed) - total_shows — total monthly impressions (главное число) - device_breakdown — {desktop, phone, tablet} if available - similar_queries — phrases users searched alongside (semantic core seed) - history — list of {date, count} if history_period != 'none' - Or isError: True on failure.

Examples: wordstat_query(query="купить iphone") → {"total_shows": 187234, "similar_queries": [...]}

wordstat_query(query="!купить +iphone +pro", region=213, history_period="monthly")
→ exact-form filtered, Moscow-only, 24-month dynamics

Inputs: query (required), region, device, history_period. Returns: object

yandex_search_api_v2A
Read-onlyIdempotent

Query Yandex Search API v2 (official) via XMLRiver proxy.

Use this when you need: cleaner structured output, no SERP-feature parsing overhead, documented Yandex Search API semantics. Slightly more expensive than yandex_search (~24 ₽/1k vs 25 ₽/1k on Basic tariff).

Do NOT use for: SERP features (knowledge graph, FAQ, related questions) — those are not in the official API. Use yandex_search instead.

Returns: Parsed search results dict similar to yandex_search but without addresults.

Inputs: query (required), region, page, group_count. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: URL indexation check, account management (balance, cost, tariff, tariff expiry), Google SERP parsing, Yandex Wordstat, Yandex SERP parsing, and Yandex Search API. There is no overlap or ambiguity.

    Naming Consistency5/5

    Tool names follow a consistent verb_noun pattern (e.g., get_balance, check_url_indexed, google_search). All are snake_case with clear verbs, making the action predictable. The naming is uniform across the set.

    Tool Count5/5

    With 9 tools, the scope is well-calibrated: 4 tools cover account and cost management, and 5 cover search engine data access (Google, Yandex, indexation, keyword research). This is a complete yet focused surface for an SEO/SERP analysis tool.

    Completeness5/5

    The tool set covers all core operations expected from an XMLRiver client: account info (balance, tariff, cost, expiry), Google and Yandex search, URL indexation checking, and keyword frequency via Wordstat. There are no obvious gaps for the stated purpose of SEO and search data retrieval.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A powerful MCP server that enables parallel Google searching with multiple keywords simultaneously, providing structured results while handling CAPTCHAs and simulating user browsing patterns.
      1
      132 npm
      272
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Yandex Direct, Metrika, Wordstat, and Webmaster APIs, providing 132 tools to manage advertising campaigns, analytics, keyword research, and reporting through any MCP-compatible client.
      58
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      MCP server that provides 46 tools for managing Yandex Webmaster API v4, enabling site management, sitemaps, indexing, search analytics, and more through natural language.
      46
      22 npm
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for querying Yandex Wordstat via Yandex Cloud Search API. Enables checking phrase frequency, similar queries, regional demand, and seasonality trends.
      2
      MIT