Xmlriver Mcp
First MCP server for XMLRiver — Russian-focused SEO API. Provides Google/Yandex SERP parsing, Yandex Wordstat keyword frequency data, and URL indexing checks via XML API. Fills the gap for Russian SEO research and Yandex-aware analysis in Claude / Cursor / Windsurf.
Tools (9 total, all read-only):
- google_search — Google SERP with country/lang/device/page filters, additional blocks (ads, FAQ, knowledge graph, AI Overview)
- yandex_search — Yandex SERP (Russian markets — primary use case) with region/domain/lang/device
- yandex_search_api_v2 — official Yandex Search API v2 via XMLRiver proxy
- wordstat_query — Yandex Wordstat keyword frequency, similar/containing phrases, history
- check_url_indexed — index check in Google or Yandex
- get_balance, get_tariff, get_tariff_expire, get_cost — account ops
Pay-as-you-go via XMLRiver (~25 ₽ / 1000 requests on Basic tariff).
GitHub: https://github.com/artgas1/xmlriver-mcp
PyPI: https://pypi.org/project/xmlriver-mcp/
Official MCP Registry: io.github.artgas1/xmlriver-mcp
Overview
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).
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, device breakdown, history, similar queries |
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.
Authentication
- Register at https://xmlriver.com
- Top up balance (minimum ~100 ₽ to start)
- Get your
user(numeric ID) andkey(40-char hex) from the dashboard - Set
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 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 - Indexation monitoring —
check_url_indexed(url="https://your-site.com/new-page")after publishing - Cross-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/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)
Built with /mcp-development
This MCP server was written using NeiroOwl's /mcp-development skill — comprehensive guide for building MCP servers in 2026 (MCP spec 2025-11-25). The skill codifies:
- Tool design (granular vs unified, 3-part descriptions, schemas, annotations)
- Anti-patterns (top 20)
- Security model (9 attack classes + defense-in-depth)
- Distribution (PyPI/npm + registries)
If you're building your own MCP — check it out.
License
Contributing
PRs welcome. Open an issue first for substantial changes.
Acknowledgements
- XMLRiver — for the underlying API
- Anthropic MCP — for the protocol
brightdata-mcp-full— patterns reference (NeiroOwl team)
Server Config
{
"mcpServers": {
"xmlriver": {
"command": "uvx",
"args": [
"xmlriver-mcp"
],
"env": {
"XMLRIVER_USER": "<your_user_id>",
"XMLRIVER_KEY": "<your_api_key>"
}
}
}
}Project Info
Created At
16 days agoUpdated At
16 days agoAuthor Name
artgas1Star
-Language
-License
-Recommend Servers
View AllTavily Mcp
@tavily-ai
JavaScript
a year ago
Mcp Server Chatsum
@chatmcp
summarize chat message
typescript
a year ago
Crevio
2 days ago
Rollinggo Hotel Mcp
@longcreat
2 days ago
Amap Maps
@amap
高德地图官方 MCP Server
a year ago
Serper MCP Server
@garymengcom
A Serper MCP Server
Python
a year ago
Test
@modelcontextprotocol
test
6 months ago