Xmlriver Mcp

xmlriver-mcp

XMLRiver 的 MCP 服务：XMLRiver — 通过 XML API 解析 Google/Yandex 搜索结果页（SERP），并获取 Yandex Wordstat 关键词频率数据。

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

功能

让 Claude / Cursor / Windsurf 直接访问：

• Google SERP 解析（自然搜索结果、广告、常见问题、知识图谱、AI 概览），支持任意国家 / 地区 / 设备
• Yandex SERP 解析（俄语市场——主要使用场景）
• Yandex Wordstat 关键词频率、历史数据和类似查询（Yandex 的关键词搜索量工具）
• 索引检查 — 检查此 URL 是否已被 Google/Yandex 收录
• 账户操作 — 余额、套餐、每 1,000 次请求的费用

首个用于 XMLRiver 的 MCP 服务——填补了俄语 SEO 研究和 Yandex 感知分析方面的空白。按使用量付费（基础套餐约为每 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–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 页面 — 绕过解析，并向模型上下文返回数 MB 内容）和延迟响应模式（delayed / req_id）— MCP 调用是同步的，因此调用方需要轮询的请求 ID 没有实用的用途。

身份验证

1. 在 https://xmlriver.com 注册
2. 充值余额（起步最低约 100 ₽）
3. 从控制面板获取 user（数字 ID）和 key（40 个字符的十六进制字符串）
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") 检查收录情况
• 跨地区对比 — 对 Yandex/Google 使用相同查询，并更改 region/country，查看地域差异

本地开发

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 协议要求 stdout 用于 JSON-RPC）

许可证

MIT

贡献

欢迎提交 PR。若要进行重大更改，请先提出 issue。

致谢

• XMLRiver — 感谢其提供底层 API
• Anthropic MCP — 感谢其提供协议