DataSEO MCP

July 6, 2026 · View on GitHub

Give your AI assistant real SEO data. DataSEO MCP is a Model Context Protocol 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. Built for the AI SEO and rank-tracking workflows behind Suparank.

Quick start

Run it with no install using 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 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.

Configuration

One CAPTCHA provider is required — it's how the Ahrefs-backed tools clear the Turnstile challenge:

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:

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:

claude mcp add dataseo --scope user -- uvx --python 3.10 dataseo-mcp

Claude Desktop / Cursor (claude_desktop_config.json or equivalent):

{
  "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):

{
  "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)`

{
  "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": "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

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.