\n\n# `xmlriver-mcp`\n\n> MCP server for [XMLRiver](https://xmlriver.com) — Google/Yandex SERP parsing and Yandex Wordstat keyword frequency data via XML API.\n\nmcp-name: io.github.artgas1/xmlriver-mcp\n\n[](cursor://anysphere.cursor-deeplink/mcp/install?name=xmlriver&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ4bWxyaXZlci1tY3AiXSwiZW52Ijp7IlhNTFJJVkVSX1VTRVIiOiI8eW91cl91c2VyX2lkPiIsIlhNTFJJVkVSX0tFWSI6Ijx5b3VyX2FwaV9rZXk+In19)\n[](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22xmlriver-mcp%22%5D%2C%22env%22%3A%7B%22XMLRIVER_USER%22%3A%22%3Cyour_user_id%3E%22%2C%22XMLRIVER_KEY%22%3A%22%3Cyour_api_key%3E%22%7D%7D)\n[](https://claude.ai/download)\n\n[](https://pypi.org/project/xmlriver-mcp/)\n[](https://pepy.tech/project/xmlriver-mcp)\n[](LICENSE)\n[](https://www.python.org/downloads/)\n\n## What it does\n\nGives Claude / Cursor / Windsurf direct access to:\n\n- **Google SERP** parsing (organic, ads, FAQ, knowledge graph, AI Overview) for any country / region / device\n- **Yandex SERP** parsing (Russian-speaking markets — primary use case)\n- **Yandex Wordstat** keyword frequency, history, similar queries (Yandex's keyword volume tool)\n- **Indexing check** — is this URL in Google/Yandex index?\n- **Account ops** — balance, tariff, cost per 1k requests\n\n**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).\n\n## Demo\n\n
\n \n
\n\nClaude queries `wordstat_query` and parses real frequency data from Yandex. Same flow works for `google_search`, `yandex_search`, indexing checks, and account ops.\n\n## Quickstart\n\n```bash\nuvx xmlriver-mcp\n```\n\n## Configuration\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"xmlriver\": {\n \"command\": \"uvx\",\n \"args\": [\"xmlriver-mcp\"],\n \"env\": {\n \"XMLRIVER_USER\": \"\",\n \"XMLRIVER_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Claude Code\n\nAdd to project `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"xmlriver\": {\n \"command\": \"uvx\",\n \"args\": [\"xmlriver-mcp\"],\n \"env\": {\n \"XMLRIVER_USER\": \"\",\n \"XMLRIVER_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Cursor\n\nEdit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n \"mcpServers\": {\n \"xmlriver\": {\n \"command\": \"uvx\",\n \"args\": [\"xmlriver-mcp\"],\n \"env\": {\n \"XMLRIVER_USER\": \"\",\n \"XMLRIVER_KEY\": \"\"\n }\n }\n }\n}\n```\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `google_search` | Parse Google SERP for a query — country, language, device, page, date filter, extra blocks (ads, FAQ, knowledge graph, AI Overview) |\n| `yandex_search` | Parse Yandex SERP — region, language, device, page, date filter, extra blocks |\n| `yandex_search_api_v2` | Yandex Search API v2 (official) via XMLRiver — cleaner structured output |\n| `wordstat_query` | Yandex Wordstat keyword frequency + similar queries, or demand dynamics by month/week/day |\n| `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 |\n| `google_maps_search` | Google Maps places around a coordinate (zoom + coords required). ⚠️ See caveat below |\n| `check_url_indexed` | Check if URL is indexed in Google or Yandex |\n| `get_balance` | Current XMLRiver balance in rubles |\n| `get_tariff` | Current XMLRiver tariff name (Basic / Pro / Mega / Giga) |\n| `get_tariff_expire` | Tariff expiration date (for prepay tariffs) |\n| `get_cost` | Cost per 1000 requests for a given engine (google / yandex / yaxml / wordstat) |\n\nAll tools are **read-only** (annotated with `readOnlyHint: true`). No destructive operations.\n\n⚠️ **`google_maps_search` is unverified against a live response.** Every `setab=maps` request\nanswered `code 500` while it was written (2026-08-04), including a deliberately invalid one that\nshould have returned `code 108` — plain Google and Yandex searches worked in the same minutes, so\nthe mode appears unavailable service-side. The request shape and response parsing follow the\ndocumentation and are covered by unit tests; both still need a live check.\n\n**Deliberately not wrapped:** `raw=page` (returns the full HTML page — bypasses parsing and\nreturns megabytes into the model's context) and the deferred-response mode (`delayed` / `req_id`)\n— an MCP call is synchronous, so a request id the caller must poll for has nowhere useful to go.\n\n## Authentication\n\n1. Register at https://xmlriver.com\n2. Top up balance (minimum ~100 ₽ to start)\n3. Get your `user` (numeric ID) and `key` (40-char hex) from the dashboard\n4. Set `XMLRIVER_USER` and `XMLRIVER_KEY` env vars in your MCP client config\n\n**Security note:** XMLRiver API is HTTP-only (not HTTPS). The key is rotatable from the dashboard if compromised.\n\n## Pricing context\n\n| Tariff | Setup | Google / Yandex / Wordstat | Yandex Search API v2 |\n|---|---|---|---|\n| **Basic** | Pay-as-you-go | 25 ₽ / 1k | 25 ₽ / 1k |\n| Pro | 5000 ₽/mo | 20 ₽ / 1k | 24 ₽ / 1k |\n| Mega | 15000 ₽/mo | 15 ₽ / 1k | 23 ₽ / 1k |\n| Giga | 50000 ₽/mo | 12 ₽ / 1k | 22 ₽ / 1k |\n\nUse `get_balance` and `get_cost` to monitor spend before bulk operations.\n\n## Common use cases\n\n- **SEO position tracking** — `yandex_search(query=\"...\", region=213)` for own/competitor ranking\n- **Keyword research** — `wordstat_query(query=\"купить iphone\", history_period=\"monthly\")` for demand validation + seasonality\n- **Featured snippet hunting** — `google_search(additional_blocks=\"faqsnippet,knowledge_graph,zeroposition\")` to see what owns the answer box\n- **Long-tail discovery** — `search_suggestions(phrases=[...])` with a prefix sweep (seed + each letter of the alphabet) pulls phrasings Wordstat never reports\n- **Indexation monitoring** — `check_url_indexed(url=\"https://your-site.com/new-page\")` after publishing\n- **Cross-region comparison** — same query, different `region`/`country` for Yandex/Google to see geographic variance\n\n## Local development\n\n```bash\ngit clone https://github.com/artgas1/xmlriver-mcp\ncd xmlriver-mcp\nuv sync --all-extras\n\n# Run unit tests (no API key needed)\nuv run pytest tests/unit -v\n\n# Run integration tests (requires XMLRIVER_USER / XMLRIVER_KEY)\nXMLRIVER_USER=... XMLRIVER_KEY=... uv run pytest tests/integration -v -m integration\n\n# MCP Inspector — interactive\nXMLRIVER_USER=... XMLRIVER_KEY=... npx @modelcontextprotocol/inspector uv run python -m xmlriver_mcp.server\n\n# MCP Inspector — CLI smoke test (list tools)\nnpx @modelcontextprotocol/inspector --cli \"uv run python -m xmlriver_mcp.server\" --method tools/list\n```\n\n## Architecture\n\n- **Stack:** Python 3.10+ / [FastMCP](https://github.com/jlowin/fastmcp) / httpx / tenacity / pydantic\n- **Transport:** stdio (default)\n- **No external SDK dependency** — direct REST via httpx + custom XML parser\n- **Retry strategy:** 3 attempts with exponential backoff on network errors (not on HTTP 4xx)\n- **Logging:** stderr only (stdio protocol requires stdout for JSON-RPC)\n\n## License\n\n[MIT](LICENSE)\n\n## Contributing\n\nPRs welcome. Open an issue first for substantial changes.\n\n## Acknowledgements\n\n- [XMLRiver](https://xmlriver.com) — for the underlying API\n- [Anthropic MCP](https://modelcontextprotocol.io) — for the protocol\n",
"bytes": 8273,
"sha": "a6a9603fb7c23943ad9934337ad77475c2078ef97d5d98ee9ae53d3f1af7fc1d",
"repo_slug": "artgas1/xmlriver-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_artgas1_xmlriver_mcp_f5a7990c/readme"
}
![\"xmlriver-mcp](\"assets/icon.svg\"){kind=icon}
\n![\"xmlriver-mcp](\"assets/demo-wordstat.png\")
\n