DataSEO MCP

DataSEO MCP is a Model Context Protocol server for practical SEO research in AI assistants. It combines Ahrefs free SEO data, CAPTCHA-provider fallback, and optional OpenRouter-powered query planning behind a small set of MCP tools.

[!CAUTION] This project is for educational and research purposes only. It interacts with third-party services including Ahrefs, CapSolver, Anti-Captcha, and OpenRouter. Users are responsible for complying with all applicable terms of service.

Features

DataSEO MCP is maintained by Ege Bese. For AI SEO and rank-tracking workflows, see Suparank.

Installation

bashCopy code
uvx --python 3.10 dataseo-mcp

For local development:

bashCopy code
git clone https://github.com/egebese/dataseo-mcp.git
cd dataseo-mcp
uv sync
uv run dataseo-mcp

The legacy seo-mcp command is still exposed as a compatibility alias.

Configuration

At least one CAPTCHA provider is required for Ahrefs-backed tools:

bashCopy code
export CAPSOLVER_API_KEY="your-capsolver-key"
# or
export ANTICAPTCHA_API_KEY="your-anticaptcha-key"

If both are configured, CapSolver is tried first and Anti-Captcha is used as fallback. AI tools are optional:

bashCopy code
export OPENROUTER_API_KEY="your-openrouter-key"
export OPENROUTER_MODEL="openai/gpt-4o-mini"  # optional

Useful runtime overrides:

MCP Setup

Claude Desktop / Cursor-style config:

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

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

VS Code MCP config:

jsonCopy code
{
  "servers": {
    "dataseo": {
      "command": "uvx",
      "args": ["--python", "3.10", "dataseo-mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_KEY"
      }
    }
  }
}

Only one CAPTCHA provider key is required. Add OPENROUTER_API_KEY only when you want AI-assisted query generation or content briefs.

API Reference

get_backlinks_list(domain)

Returns:

jsonCopy code
{
  "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")

Returns keyword and question ideas in the existing label / value shape.

get_traffic(domain_or_url, country="None", mode="subdomains")

Returns traffic history, traffic summary, top pages, countries, and keywords. The legacy costMontlyAvg field is preserved and costMonthlyAvg is also included.

keyword_difficulty(keyword, country="us")

Returns a keyword difficulty score and organic SERP rows with available metrics.

ai_search_queries(keyword, count=10, model="openai/gpt-4o-mini", language="en")

Returns deduplicated AI-generated queries:

jsonCopy code
{
  "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 validated from 1 to 50. Valid intents are informational, commercial, transactional, and navigational.

Additional Tools

• domain_overview(domain, country="None"): backlink overview plus traffic summary for one domain.
• compare_domains(domains, country="None"): compares 2-5 unique domains.
• backlink_opportunities(domain, competitors): lists competitor backlink sources not present in the target sample.
• seo_content_brief(keyword, country="us", count=12, model, language): combines keyword difficulty, SERP rows, AI search queries, and recommended content angles.

Architecture

server.py is intentionally thin. The implementation is split into:

• services.py: MCP 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/OpenAI-compatible query generation.
• cache.py: JSON signature cache under ~/.cache/dataseo-mcp by default.

All external HTTP boundaries are mocked in tests.

Development

bashCopy code
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 educational-use notice. Original fork attribution is preserved in LICENSE.