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.

What you can ask

Talk to it in natural language — the assistant picks the right tool.

Maintained by Ege Bese. Built for the AI SEO and rank-tracking workflows behind Suparank.

Related MCP server: SE Ranking MCP Server

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:

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

License

MIT with an educational-use notice. Original fork attribution is preserved in LICENSE.