内容
<p align="center">
<img src="assets/icon.svg" width="96" alt="xmlriver-mcp logo">
</p>
# xmlriver-mcp
> XMLRiver 的 MCP 服务器 — 通过 XML API 提供 Google/Yandex SERP 解析和 Yandex Wordstat 关键词频率数据。
mcp-name: io.github.artgas1/xmlriver-mcp
[](cursor://anysphere.cursor-deeplink/mcp/install?name=xmlriver&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ4bWxyaXZlci1tY3AiXSwiZW52Ijp7IlhNTFJJVkVSX1VTRVIiOiI8eW91cl91c2VyX2lkPiIsIlhNTFJJVkVSX0tFWSI6Ijx5b3VyX2FwaV9rZXk+In19)
[](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22command%22%3A%22ud4x%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)
[](https://claude.ai/download)
[](https://pypi.org/project/xmlriver-mcp/)
[](https://pepy.tech/project/xmlriver-mcp)
[](LICENSE)
[](https://www.python.org/downloads/)
## 功能
为 Claude / Cursor / Windsurf 提供直接访问：
- **Google SERP** 解析（自然搜索结果、广告、FAQ、知识图谱、AI 概览）适用于任何国家/地区/设备
- **Yandex SERP** 解析（俄语市场 - 主要用例）
- **Yandex Wordstat** 关键词频率、历史、相似查询（Yandex 的关键词量工具）
- **索引检查** - 该 URL 是否在 Google/Yandex 索引中？
- **账户操作** - 余额、关税、每 1000 个请求成本
**首个 XMLRiver 的 MCP** - 填补了俄语 SEO 研究和 Yandex 感知分析的空白。按需付费（基本套餐约 25 ₽ / 1000 请求）。
## 演示
<p align="center">
<img src="assets/demo-wordstat.png" width="720" alt="xmlriver-mcp wordstat demo in Claude">
</p>
Claude 查询 `wordstat_query` 并解析来自 Yandex 的真实频率数据。相同的流程适用于 `google_search`、`yandex_search`、索引检查和账户操作。
## 快速入门
```bash
uvx xmlriver-mcp
```
## 配置
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"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`：
```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`（项目）：
```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 概览） |
| `yandex_search` | 解析 Yandex SERP - 地区、语言、设备、页面、日期筛选、额外块 |
| `yandex_search_api_v2` | Yandex Search API v2（官方）通过 XMLRiver - 更干净的结构化输出 |
| `wordstat_query` | Yandex Wordstat 关键词频率、设备细分、历史、相似查询 |
| `check_url_indexed` | 检查 URL 是否在 Google 或 Yandex 索引中 |
| `get_balance` | 当前 XMLRiver 余额（卢布） |
| `get_tariff` | 当前 XMLRiver 关税名称（Basic / Pro / Mega / Giga） |
| `get_tariff_expire` | 关税到期日期（预付费关税） |
| `get_cost` | 给定引擎的每 1000 个请求成本（google / yandex / yaxml / wordstat） |
所有工具均为**只读**（标注为 `readOnlyHint: true`）。无破坏性操作。
## 身份验证
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 ₽/月 | 20 ₽ / 1k | 24 ₽ / 1k |
| Mega | 15000 ₽/月 | 15 ₽ / 1k | 23 ₽ / 1k |
| Giga | 50000 ₽/月 | 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")` 查看谁拥有答案框
- **索引监控** - `check_url_indexed(url="https://your-site.com/new-page")` 发布后
- **跨地区比较** - 相同查询，不同 `region`/`country` 用于 Yandex/Google 查看地理差异
## 本地开发
```bash
git clone https://github.com/artgas1/xmlriver-mcp
cd xmlriver-mcp
uv sync --all-extras
# 运行单元测试（无需 API 密钥）
uv run pytest tests/unit -v
# 运行集成测试（需要 XMLRIVER_USER / XMLRIVER_KEY）
XMLRIVER_USER=... XMLRIVER_KEY=... uv run pytest tests/integration -v -m integration
# MCP Inspector - 交互式
XMLRIVER_USER=... XMLRIVER_KEY=... npx @modelcontextprotocol/inspector uv run python -m xmlriver_mcp.server
# MCP Inspector - CLI 烟雾测试（列出工具）
npx @modelcontextprotocol/inspector --cli "uv run python -m xmlriver_mcp.server" --method tools/list
```
## 架构
- **堆栈：** Python 3.10+ / [FastMCP](https://github.com/jlowin/fastmcp) / httpx / tenacity / pydantic
- **传输：** stdio（默认）
- **无外部 SDK 依赖** - 直接 REST 调用 httpx + 自定义 XML 解析器
- **重试策略：** 网络错误时 3 次尝试，指数退避（非 HTTP 4xx 错误）
- **日志记录：** 仅 stderr（stdio 协议需要 stdout 进行 JSON-RPC）
## 许可证
[MIT](LICENSE)
## 贡献
欢迎 PR。重大更改请先开启 issue。
## 致谢
- [XMLRiver](https://xmlriver.com) - 底层 API
- [Anthropic MCP](https://modelcontextprotocol.io) - 协议
