Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/egebese--dataseo-mcp/badge.svg)](/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

i

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)

  1. # DataSEO MCP
  2. Give your AI assistant real SEO data. DataSEO MCP is a [Model Context
  3. Protocol](https://modelcontextprotocol.io) server that lets Claude, Cursor, and
  4. other MCP clients pull **backlinks, keyword difficulty, traffic estimates, and
  5. keyword ideas** from Ahrefs' free tools — plus optional AI query planning — just
  6. by asking in plain English.
  7. No dashboards, no CSV exports. Ask *"who links to suparank.io?"* and get an
  8. answer inside your chat.
  9. > [!CAUTION]
  10. > For educational and research use. It automates third-party services (Ahrefs,
  11. > CapSolver, Anti-Captcha, OpenRouter). You are responsible for complying with
  12. > their terms of service.
  13. ## What you can ask
  14. Talk to it in natural language — the assistant picks the right tool.
  15. | Ask something like… | Tool it uses | You get |
  16. | --- | --- | --- |
  17. | "Who links to suparank.io?" | `get_backlinks_list` | Domain rating, referring domains, top backlink rows |
  18. | "Give me keyword ideas for AI SEO tools" | `keyword_generator` | Keyword and question ideas |
  19. | "How much organic traffic does suparank.io get?" | `get_traffic` | Monthly traffic, top pages, countries, keywords |
  20. | "How hard is it to rank for 'AI SEO tools'?" | `keyword_difficulty` | KD score + the live SERP |
  21. | "Generate AI search queries for 'AI SEO audit'" | `ai_search_queries` | Queries grouped by search intent |
  22. | "Give me an SEO overview of suparank.io" | `domain_overview` | Backlink + traffic summary in one call |
  23. | "Compare suparank.io with its competitors" | `compare_domains` | 2–5 domains side by side |
  24. | "Find backlink gaps for suparank.io" | `backlink_opportunities` | Sources linking to competitors but not you |
  25. | "Write a content brief for 'AI SEO audit'" | `seo_content_brief` | SERP data + AI-assisted content angles |
  26. Maintained by [Ege Bese](https://egebese.com). Built for the AI SEO and
  27. rank-tracking workflows behind [Suparank](https://suparank.io).
  28. ## Quick start
  29. Run it with no install using [`uv`](https://docs.astral.sh/uv/):
  30. ```bash
  31. export CAPSOLVER_API_KEY="your-capsolver-key"
  32. uvx --python 3.10 dataseo-mcp
  33. ```
  34. That's enough to use every SEO tool. See [MCP Setup](#mcp-setup) to wire it into
  35. your assistant.
  36. For local development:
  37. ```bash
  38. git clone https://github.com/egebese/dataseo-mcp.git
  39. cd dataseo-mcp
  40. uv sync
  41. uv run dataseo-mcp
  42. ```
  43. The legacy `seo-mcp` command still works as an alias.
  44. ## Configuration
  45. **One CAPTCHA provider is required** — it's how the Ahrefs-backed tools clear
  46. the Turnstile challenge:
  47. ```bash
  48. export CAPSOLVER_API_KEY="your-capsolver-key"
  49. # or
  50. export ANTICAPTCHA_API_KEY="your-anticaptcha-key"
  51. ```
  52. If both are set, CapSolver is tried first and Anti-Captcha is the fallback.
  53. **AI tools are optional.** `ai_search_queries` and `seo_content_brief` need
  54. OpenRouter; without it, the other tools still work and AI output is marked
  55. unavailable:
  56. ```bash
  57. export OPENROUTER_API_KEY="your-openrouter-key"
  58. export OPENROUTER_MODEL="openai/gpt-4o-mini" # optional
  59. ```
  60. Runtime overrides:
  61. | Variable | Default | Purpose |
  62. | --- | --- | --- |
  63. | `DATASEO_CACHE_DIR` | `~/.cache/dataseo-mcp` | Signature cache location |
  64. | `DATASEO_REQUEST_TIMEOUT` | `30` | HTTP timeout in seconds |
  65. | `DATASEO_MAX_POLLING_ATTEMPTS` | `120` | CAPTCHA polling cap |
  66. | `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | OpenAI-compatible AI endpoint |
  67. ## MCP Setup
  68. **Claude Code:**
  69. ```bash
  70. claude mcp add dataseo --scope user -- uvx --python 3.10 dataseo-mcp
  71. ```
  72. **Claude Desktop / Cursor** (`claude_desktop_config.json` or equivalent):
  73. ```json
  74. {
  75. "mcpServers": {
  76. "dataseo": {
  77. "command": "uvx",
  78. "args": ["--python", "3.10", "dataseo-mcp"],
  79. "env": {
  80. "CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_KEY",
  81. "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY"
  82. }
  83. }
  84. }
  85. }
  86. ```
  87. **VS Code** (`.vscode/mcp.json`):
  88. ```json
  89. {
  90. "servers": {
  91. "dataseo": {
  92. "command": "uvx",
  93. "args": ["--python", "3.10", "dataseo-mcp"],
  94. "env": { "CAPSOLVER_API_KEY": "YOUR_CAPSOLVER_KEY" }
  95. }
  96. }
  97. }
  98. ```
  99. Add `OPENROUTER_API_KEY` only if you want the AI tools.
  100. ## API Reference
  101. ### `get_backlinks_list(domain)`
  102. ```json
  103. {
  104. "overview": { "domainRating": 76, "backlinks": 1500, "refdomains": 300 },
  105. "backlinks": [
  106. {
  107. "anchor": "Suparank",
  108. "domainRating": 71,
  109. "title": "The best AI SEO tools",
  110. "urlFrom": "https://source.example/best-seo-tools",
  111. "urlTo": "https://suparank.io/",
  112. "edu": false,
  113. "gov": false
  114. }
  115. ]
  116. }
  117. ```
  118. ### `keyword_generator(keyword, country="us", search_engine="Google")`
  119. Keyword and question ideas in the `label` / `value` shape. Volume and difficulty
  120. come back as Ahrefs' bucketed estimates.
  121. ### `get_traffic(domain_or_url, country="None", mode="subdomains")`
  122. Traffic history, traffic summary, and top pages / countries / keywords. Both
  123. `costMonthlyAvg` and the legacy `costMontlyAvg` spelling are included.
  124. ### `keyword_difficulty(keyword, country="us")`
  125. A keyword difficulty score plus the organic SERP rows with available metrics.
  126. ### `ai_search_queries(keyword, count=10, model="openai/gpt-4o-mini", language="en")`
  127. ```json
  128. {
  129. "keyword": "ai seo audit",
  130. "queries": [
  131. { "query": "what is an AI SEO audit", "intent": "informational" },
  132. { "query": "best AI SEO audit tools", "intent": "commercial" }
  133. ],
  134. "model_used": "openai/gpt-4o-mini",
  135. "total_queries": 2
  136. }
  137. ```
  138. `count` is 1–50. Intents are `informational`, `commercial`, `transactional`,
  139. `navigational`.
  140. ### Composite tools
  141. - `domain_overview(domain, country="None")` — backlink overview + traffic
  142. summary for one domain.
  143. - `compare_domains(domains, country="None")` — 2–5 unique domains side by side.
  144. - `backlink_opportunities(domain, competitors)` — competitor backlink sources
  145. missing from the target's sample.
  146. - `seo_content_brief(keyword, country="us", count=12, model, language)` — keyword
  147. difficulty, SERP rows, AI queries, and recommended content angles in one call.
  148. ## How it works
  149. `server.py` stays thin; the work is split into focused modules:
  150. - `services.py` — tool orchestration and public return shapes.
  151. - `schemas.py` — Pydantic validation and normalization.
  152. - `captcha.py` — CapSolver / Anti-Captcha fallback with bounded polling.
  153. - `backlinks.py`, `keywords.py`, `traffic.py` — Ahrefs endpoint adapters.
  154. - `ai.py` — OpenRouter query generation.
  155. - `cache.py` — JSON signature cache (default `~/.cache/dataseo-mcp`).
  156. Every external HTTP boundary is mocked in tests.
  157. ## Development
  158. ```bash
  159. uv sync
  160. uv run pytest -q
  161. uv run ruff check .
  162. uv run python -m compileall -q src
  163. uv run python -c "from seo_mcp.server import main"
  164. ```
  165. ## Troubleshooting
  166. | Problem | Fix |
  167. | --- | --- |
  168. | No CAPTCHA provider configured | Set `CAPSOLVER_API_KEY` or `ANTICAPTCHA_API_KEY` |
  169. | CAPTCHA solving failed | Check provider balance, key validity, and rate limits |
  170. | AI tool returns a missing-key error | Set `OPENROUTER_API_KEY` |
  171. | Empty SEO response | The domain or keyword may not be indexed upstream |
  172. | `seo-mcp` command not documented | Use `dataseo-mcp`; `seo-mcp` still works as an alias |
  173. ## License
  174. MIT with an educational-use notice. Original fork attribution is preserved in
  175. [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.