egebese/dataseo-mcp
GitHub: egebese/dataseo-mcp
基于 MCP 协议的免费 SEO 研究工具，将 Ahrefs 数据直接集成到 AI 编程环境中，支持关键词研究、反向链接分析和内容简报生成等功能。
Stars: 175 | Forks: 26
# DataSEO MCP
DataSEO MCP 是一个用于 AI 助手中实用 SEO 研究的模型上下文协议服务器。它整合了 Ahrefs 的免费 SEO 数据、CAPTCHA 服务提供商备用方案，以及可选的基于 OpenRouter 的查询规划，封装在少量 MCP 工具中。
## 功能
| 工具 | 用途 | 提示词示例 |
| --- | --- | --- |
| `get_backlinks_list` | 反向链接概览及顶级反向链接行 | "Show backlinks for suparank.io" |
| `keyword_generator` | 关键词和问题想法 | "Find SaaS SEO keywords for onboarding" |
| `get_traffic` | 自然流量估算 | "Estimate traffic for ege.md" |
| `keyword_difficulty` | KD 和 SERP 快照 | "Check difficulty for AI SEO tools" |
| `ai_search_queries` | 按搜索意图分类的 AI 查询建议 | "Generate AI search queries for SaaS SEO" |
| `domain_overview` | 单个域名的反向链接 + 流量摘要 | "Summarize suparank.io" |
| `compare_domains` | 比较 2-5 个域名 | "Compare suparank.io and ahrefs.com" |
| `backlink_opportunities` | 竞争对手反向链接来源缺口 | "Find backlink gaps for my domain" |
| `seo_content_brief` | SERP + AI 辅助的内容简报 | "Create a content brief for AI SEO audit" |
DataSEO MCP 由 [Ege Bese](https://ege.md) 维护。有关 AI SEO 和排名跟踪工作流，请参阅 [Suparank](https://suparank.io)。
## 安装
```
uvx --python 3.10 dataseo-mcp
```
用于本地开发：
```
git clone https://github.com/egebese/dataseo-mcp.git
cd dataseo-mcp
uv sync
uv run dataseo-mcp
```
旧的 `seo-mcp` 命令仍作为兼容性别名暴露。
## 配置
基于 Ahrefs 的工具至少需要一个 CAPTCHA 提供商：
```
export CAPSOLVER_API_KEY="your-capsolver-key"
# 或
export ANTICAPTCHA_API_KEY="your-anticaptcha-key"
```
如果两者都已配置，将首先尝试 CapSolver，并将 Anti-Captcha 用作备用方案。AI 工具是可选的：
```
export OPENROUTER_API_KEY="your-openrouter-key"
export OPENROUTER_MODEL="openai/gpt-4o-mini" # optional
```
有用的运行时覆盖配置：
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `DATASEO_CACHE_DIR` | `~/.cache/dataseo-mcp` | 签名缓存位置 |
| `DATASEO_REQUEST_TIMEOUT` | `30` | HTTP 超时时间（秒） |
| `DATASEO_MAX_POLLING_ATTEMPTS` | `120` | CAPTCHA 轮询上限 |
| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | 兼容 OpenAI 的 AI 端点 |
## MCP 设置
Claude Desktop / Cursor 风格的配置：
```
{
"mcpServers": {
"dataseo": {
"command": "uvx",
"args": ["--python", "3.10", "dataseo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_KEY",
"ANTICAPTCHA_API_KEY": "YOUR_ANTICAPTCHA_KEY",
"OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY"
}
}
}
}
```
Claude Code：
```
claude mcp add dataseo --scope user -- uvx --python 3.10 dataseo-mcp
```
VS Code MCP 配置：
```
{
"servers": {
"dataseo": {
"command": "uvx",
"args": ["--python", "3.10", "dataseo-mcp"],
"env": {
"CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_KEY"
}
}
}
}
```
只需要一个 CAPTCHA 提供商密钥。仅当您需要 AI 辅助的查询生成或内容简报时才添加 `OPENROUTER_API_KEY`。
## API 参考
### `get_backlinks_list(domain)`
返回值：
```
{
"overview": {
"domainRating": 76,
"backlinks": 1500,
"refDomains": 300
},
"backlinks": [
{
"anchor": "DataSEO MCP",
"domainRating": 76,
"title": "Example page",
"urlFrom": "https://source.example/page",
"urlTo": "https://example.com/page",
"edu": false,
"gov": false
}
]
}
```
### `keyword_generator(keyword, country="us", search_engine="Google")`
以现有的 `label` / `value` 结构返回关键词和问题想法。
### `get_traffic(domain_or_url, country="None", mode="subdomains")`
返回流量历史记录、流量摘要、热门页面、国家和关键词。旧的 `costMontlyAvg` 字段被保留，同时还包括了 `costMonthlyAvg`。
### `keyword_difficulty(keyword, country="us")`
返回关键词难度得分以及带有可用指标的自然 SERP 行。
### `ai_search_queries(keyword, count=10, model="openai/gpt-4o-mini", language="en")`
返回去重后的 AI 生成查询：
```
{
"keyword": "ai seo audit",
"queries": [
{"query": "what is an AI SEO audit", "intent": "informational"},
{"query": "best AI SEO audit tools", "intent": "commercial"}
],
"model_used": "openai/gpt-4o-mini",
"total_queries": 2
}
```
`count` 的有效验证范围为 1 到 50。有效的意图包括 `informational`、`commercial`、`transactional` 和 `navigational`。
### 其他工具
- `domain_overview(domain, country="None")`：单个域名的反向链接概览及流量摘要。
- `compare_domains(domains, country="None")`：比较 2-5 个不重复的域名。
- `backlink_opportunities(domain, competitors)`：列出目标样本中不存在的竞争对手反向链接来源。
- `seo_content_brief(keyword, country="us", count=12, model, language)`：结合关键词难度、SERP 行、AI 搜索查询和建议的内容角度。
## 架构
`server.py` 被有意保持精简。实现被拆分为：
- `services.py`：MCP 工具编排和公共返回结构。
- `schemas.py`：Pydantic 验证和规范化。
- `captcha.py`：CapSolver / Anti-Captcha 备用方案与有界轮询。
- `backlinks.py`、`keywords.py`、`traffic.py`：Ahrefs 端点适配器。
- `ai.py`：兼容 OpenRouter/OpenAI 的查询生成。
- `cache.py`：默认位于 `~/.cache/dataseo-mcp` 下的 JSON 签名缓存。
测试中模拟了所有外部 HTTP 边界。
## 开发
```
uv sync
uv run pytest -q
uv run ruff check .
uv run python -m compileall -q src
uv run python -c "from seo_mcp.server import main"
```
## 故障排除
| 问题 | 解决方案 |
| --- | --- |
| 未配置 CAPTCHA 提供商 | 设置 `CAPSOLVER_API_KEY` 或 `ANTICAPTCHA_API_KEY` |
| CAPTCHA 解析失败 | 检查提供商余额、密钥有效性和速率限制 |
| AI 工具返回缺少密钥错误 | 设置 `OPENROUTER_API_KEY` |
| SEO 响应为空 | 域名或关键词可能未被上游源索引 |
| 旧命令不再记录在案 | 使用 `dataseo-mcp`；`seo-mcp` 仍可用作别名 |
## 许可证
附带教育用途声明的 MIT 许可证。原始 fork 的归属保留在 [LICENSE](LICENSE) 中。
标签：Ahrefs, AI编程助手, CAPTCHA绕过, DLL 劫持, MCP, OpenRouter, Python, SEO工具, SEO数据挖掘, uv, 关键词研究, 内容生成, 反向链接分析, 域名对比, 大语言模型, 开源, 技术栈, 搜索引擎优化, 无后门, 模型上下文协议, 流量估算, 竞争分析, 逆向工具