DataSEO MCP

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_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")

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