xmlriver-mcp
This MCP server provides read-only access to XMLRiver's API for SEO research, SERP parsing, and keyword analysis across Google and Yandex.
Search & SERP Parsing
google_search— Parse Google SERP for any query with country/language/device targeting, pagination, date filters, and extra blocks (ads, FAQ, knowledge graph, AI Overview, related searches)yandex_search— Parse Yandex SERP with Russian region targeting, device emulation, and extra blocks — ideal for Russian-speaking market SEOyandex_search_api_v2— Query Yandex via the official Search API v2 proxy for cleaner, structured output
Keyword Research
wordstat_query— Get Yandex Wordstat keyword frequency, device breakdown, similar/related queries, and historical demand trends (monthly or weekly)
Indexation Monitoring
check_url_indexed— Verify whether a URL is indexed in Google or Yandex
Account & Billing Management
get_balance— Check current XMLRiver account balance (in rubles)get_tariff— View active tariff plan (Basic / Pro / Mega / Giga)get_tariff_expire— Check prepay tariff expiration dateget_cost— Get cost per 1,000 requests for a specific engine (google, yandex, yaxml, wordstat)
All operations are read-only (no destructive actions). Supports use cases like rank tracking, keyword research, competitor analysis, indexation audits, and cross-region comparison.
Provides tools for parsing Google SERP results, including organic, ads, FAQ, knowledge graph, and AI Overview, with support for country, region, device, page, date filters, and indexing checks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xmlriver-mcp google search for 'best SEO tools'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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-mcpConfiguration
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 |
| Parse Google SERP for a query — country, language, device, page, date filter, extra blocks (ads, FAQ, knowledge graph, AI Overview) |
| Parse Yandex SERP — region, language, device, page, date filter, extra blocks |
| Yandex Search API v2 (official) via XMLRiver — cleaner structured output |
| Yandex Wordstat keyword frequency + similar queries, or demand dynamics by month/week/day |
| 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 places around a coordinate (zoom + coords required). ⚠️ See caveat below |
| Check if URL is indexed in Google or Yandex |
| Current XMLRiver balance in rubles |
| Current XMLRiver tariff name (Basic / Pro / Mega / Giga) |
| Tariff expiration date (for prepay tariffs) |
| 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
Register at https://xmlriver.com
Top up balance (minimum ~100 ₽ to start)
Get your
user(numeric ID) andkey(40-char hex) from the dashboardSet
XMLRIVER_USERandXMLRIVER_KEYenv 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 rankingKeyword research —
wordstat_query(query="купить iphone", history_period="monthly")for demand validation + seasonalityFeatured snippet hunting —
google_search(additional_blocks="faqsnippet,knowledge_graph,zeroposition")to see what owns the answer boxLong-tail discovery —
search_suggestions(phrases=[...])with a prefix sweep (seed + each letter of the alphabet) pulls phrasings Wordstat never reportsIndexation monitoring —
check_url_indexed(url="https://your-site.com/new-page")after publishingCross-region comparison — same query, different
region/countryfor 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/listArchitecture
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
Contributing
PRs welcome. Open an issue first for substantial changes.
Acknowledgements
XMLRiver — for the underlying API
Anthropic MCP — for the protocol
Available Tools
9 toolscheck_url_indexedARead-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_balanceARead-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_costARead-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_tariffARead-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_expireARead-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
google_searchARead-onlyIdempotent
Parse Google search results page (SERP) for a given query and locale.
Use this for: SEO research (own/competitor ranking), keyword discovery, SERP feature analysis (featured snippets, knowledge graph, FAQ), competitive intel.
Do NOT use for: live page content fetching (use a dedicated scraper for that),
Google Ads keyword planner data (use Yandex Wordstat via wordstat_query for RU).
Returns:
Dict with:
- query (echoed)
- total_found — Google's reported result count
- page — page number
- results — list of organic results with position, url, title, snippet
- addresults — featured_snippet, related_questions, related_searches,
knowledge_graph (if present and requested via additional_blocks)
- Or isError: True on XMLRiver error (15 = no results, 110 = rate limit, etc).
Examples: google_search(query="python tutorial", country=2008, language="ru") → {"results": [...10 organic results...], "total_found": 12300, "page": 1}
google_search(query="site:wikipedia.org python", country=2840, language="en")
→ results restricted to wikipedia.org domainInputs: query (required), country, domain, language, +6 more. Returns: object
wordstat_queryARead-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 dynamicsInputs: query (required), region, device, history_period. Returns: object
yandex_searchARead-onlyIdempotent
Parse Yandex search results page (SERP) for a given query and region.
Use this for: Russian SEO research (own/competitor ranking in Yandex), regional keyword analysis, SERP feature analysis (FAQ, knowledge graph), competitive intel for Russian-speaking markets.
Do NOT use for: keyword frequency data — use wordstat_query instead.
Do NOT use for: structured JSON output — use yandex_search_api_v2 instead
(official Yandex Search API proxy, cleaner JSON).
Returns:
Dict with results (organic 10 items), total_found, page, addresults
(related_questions, knowledge_graph, etc), or isError: True on failure.
Examples: yandex_search(query="купить iphone", region=213) → top 10 organic for Moscow
yandex_search(query="site:wildberries.ru игрушки", region=2)
→ site-restricted search for St. Petersburg
yandex_search(query="новости", within="77")
→ last-24-hours filteredInputs: query (required), region, domain, language, +5 more. Returns: object
yandex_search_api_v2ARead-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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Remote MCP server for Google SERP, SEO research and web scraping. Free plan, no card.
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
SEO MCP server for keyword research, live SERPs, backlinks, site audits and AI visibility.
MCP server for Google search results via SERP API
Related MCP Servers
- AlicenseBqualityDmaintenanceA powerful MCP server that enables parallel Google searching with multiple keywords simultaneously, providing structured results while handling CAPTCHAs and simulating user browsing patterns.1132 npm272MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.58MIT
- AlicenseCqualityDmaintenanceMCP server that provides 46 tools for managing Yandex Webmaster API v4, enabling site management, sitemaps, indexing, search analytics, and more through natural language.4622 npm8MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for querying Yandex Wordstat via Yandex Cloud Search API. Enables checking phrase frequency, similar queries, regional demand, and seasonality trends.2MIT