dataseo-mcp
A free SEO research tool using Model Context Protocol (MCP) powered by Ahrefs data. Get backlink analysis, keyword research, traffic estimation, and more — directly in your AI-powered IDE.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/egebese--dataseo-mcp)HTML
<a href="/listings/egebese--dataseo-mcp"><img src="/api/listings/egebese--dataseo-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Run it with no install using [`uv`](https://docs.astral.sh/uv/):
export CAPSOLVER_API_KEY="your-capsolver-key" uvx --python 3.10 dataseo-mcp
That's enough to use every SEO tool. See [MCP Setup](#mcp-setup) to wire it into your assistant.
For local development:
git clone https://github.com/egebese/dataseo-mcp.git cd dataseo-mcp uv sync uv run dataseo-mcp
The legacy `seo-mcp` command still works as an alias.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 229 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # DataSEO MCP
- Give your AI assistant real SEO data. DataSEO MCP is a [Model Context
- Protocol](https://modelcontextprotocol.io) server that lets Claude, Cursor, and
- other MCP clients pull **backlinks, keyword difficulty, traffic estimates, and
- keyword ideas** from Ahrefs' free tools — plus optional AI query planning — just
- by asking in plain English.
- No dashboards, no CSV exports. Ask *"who links to suparank.io?"* and get an
- answer inside your chat.
- > [!CAUTION]
- > For educational and research use. It automates third-party services (Ahrefs,
- > CapSolver, Anti-Captcha, OpenRouter). You are responsible for complying with
- > their terms of service.
- ## What you can ask
- Talk to it in natural language — the assistant picks the right tool.
- | Ask something like… | Tool it uses | You get |
- | --- | --- | --- |
- | "Who links to suparank.io?" | `get_backlinks_list` | Domain rating, referring domains, top backlink rows |
- | "Give me keyword ideas for AI SEO tools" | `keyword_generator` | Keyword and question ideas |
- | "How much organic traffic does suparank.io get?" | `get_traffic` | Monthly traffic, top pages, countries, keywords |
- | "How hard is it to rank for 'AI SEO tools'?" | `keyword_difficulty` | KD score + the live SERP |
- | "Generate AI search queries for 'AI SEO audit'" | `ai_search_queries` | Queries grouped by search intent |
- | "Give me an SEO overview of suparank.io" | `domain_overview` | Backlink + traffic summary in one call |
- | "Compare suparank.io with its competitors" | `compare_domains` | 2–5 domains side by side |
- | "Find backlink gaps for suparank.io" | `backlink_opportunities` | Sources linking to competitors but not you |
- | "Write a content brief for 'AI SEO audit'" | `seo_content_brief` | SERP data + AI-assisted content angles |
- Maintained by [Ege Bese](https://egebese.com). Built for the AI SEO and
- rank-tracking workflows behind [Suparank](https://suparank.io).
- ## Quick start
- Run it with no install using [`uv`](https://docs.astral.sh/uv/):
- ```bash
- export CAPSOLVER_API_KEY="your-capsolver-key"
- uvx --python 3.10 dataseo-mcp
- ```
- That's enough to use every SEO tool. See [MCP Setup](#mcp-setup) to wire it into
- your assistant.
- For local development:
- ```bash
- git clone https://github.com/egebese/dataseo-mcp.git
- cd dataseo-mcp
- uv sync
- uv run dataseo-mcp
- ```
- The legacy `seo-mcp` command still works as an alias.
- ## Configuration
- **One CAPTCHA provider is required** — it's how the Ahrefs-backed tools clear
- the Turnstile challenge:
- ```bash
- export CAPSOLVER_API_KEY="your-capsolver-key"
- # or
- export ANTICAPTCHA_API_KEY="your-anticaptcha-key"
- ```
- If both are set, CapSolver is tried first and Anti-Captcha is the fallback.
- **AI tools are optional.** `ai_search_queries` and `seo_content_brief` need
- OpenRouter; without it, the other tools still work and AI output is marked
- unavailable:
- ```bash
- export OPENROUTER_API_KEY="your-openrouter-key"
- export OPENROUTER_MODEL="openai/gpt-4o-mini" # optional
- ```
- Runtime overrides:
- | Variable | Default | Purpose |
- | --- | --- | --- |
- | `DATASEO_CACHE_DIR` | `~/.cache/dataseo-mcp` | Signature cache location |
- | `DATASEO_REQUEST_TIMEOUT` | `30` | HTTP timeout in seconds |
- | `DATASEO_MAX_POLLING_ATTEMPTS` | `120` | CAPTCHA polling cap |
- | `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | OpenAI-compatible AI endpoint |
- ## MCP Setup
- **Claude Code:**
- ```bash
- claude mcp add dataseo --scope user -- uvx --python 3.10 dataseo-mcp
- ```
- **Claude Desktop / Cursor** (`claude_desktop_config.json` or equivalent):
- ```json
- {
- "mcpServers": {
- "dataseo": {
- "command": "uvx",
- "args": ["--python", "3.10", "dataseo-mcp"],
- "env": {
- "CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_KEY",
- "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY"
- }
- }
- }
- }
- ```
- **VS Code** (`.vscode/mcp.json`):
- ```json
- {
- "servers": {
- "dataseo": {
- "command": "uvx",
- "args": ["--python", "3.10", "dataseo-mcp"],
- "env": { "CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_KEY" }
- }
- }
- }
- ```
- Add `OPENROUTER_API_KEY` only if you want the AI tools.
- ## API Reference
- ### `get_backlinks_list(domain)`
- ```json
- {
- "overview": { "domainRating": 76, "backlinks": 1500, "refdomains": 300 },
- "backlinks": [
- {
- "anchor": "Suparank",
- "domainRating": 71,
- "title": "The best AI SEO tools",
- "urlFrom": "https://source.example/best-seo-tools",
- "urlTo": "https://suparank.io/",
- "edu": false,
- "gov": false
- }
- ]
- }
- ```
- ### `keyword_generator(keyword, country="us", search_engine="Google")`
- Keyword and question ideas in the `label` / `value` shape. Volume and difficulty
- come back as Ahrefs' bucketed estimates.
- ### `get_traffic(domain_or_url, country="None", mode="subdomains")`
- Traffic history, traffic summary, and top pages / countries / keywords. Both
- `costMonthlyAvg` and the legacy `costMontlyAvg` spelling are included.
- ### `keyword_difficulty(keyword, country="us")`
- A keyword difficulty score plus the organic SERP rows with available metrics.
- ### `ai_search_queries(keyword, count=10, model="openai/gpt-4o-mini", language="en")`
- ```json
- {
- "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` is 1–50. Intents are `informational`, `commercial`, `transactional`,
- `navigational`.
- ### Composite tools
- - `domain_overview(domain, country="None")` — backlink overview + traffic
- summary for one domain.
- - `compare_domains(domains, country="None")` — 2–5 unique domains side by side.
- - `backlink_opportunities(domain, competitors)` — competitor backlink sources
- missing from the target's sample.
- - `seo_content_brief(keyword, country="us", count=12, model, language)` — keyword
- difficulty, SERP rows, AI queries, and recommended content angles in one call.
- ## How it works
- `server.py` stays thin; the work is split into focused modules:
- - `services.py` — tool orchestration and public return shapes.
- - `schemas.py` — Pydantic validation and normalization.
- - `captcha.py` — CapSolver / Anti-Captcha fallback with bounded polling.
- - `backlinks.py`, `keywords.py`, `traffic.py` — Ahrefs endpoint adapters.
- - `ai.py` — OpenRouter query generation.
- - `cache.py` — JSON signature cache (default `~/.cache/dataseo-mcp`).
- Every external HTTP boundary is mocked in tests.
- ## Development
- ```bash
- 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"
- ```
- ## Troubleshooting
- | Problem | Fix |
- | --- | --- |
- | No CAPTCHA provider configured | Set `CAPSOLVER_API_KEY` or `ANTICAPTCHA_API_KEY` |
- | CAPTCHA solving failed | Check provider balance, key validity, and rate limits |
- | AI tool returns a missing-key error | Set `OPENROUTER_API_KEY` |
- | Empty SEO response | The domain or keyword may not be indexed upstream |
- | `seo-mcp` command not documented | Use `dataseo-mcp`; `seo-mcp` still works as an alias |
- ## License
- MIT with an educational-use notice. Original fork attribution is preserved in
- [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.