ahrefs-mcp - SKILL.md Agent Skill

name: ahrefs-mcp description: Provides configuration, working code, and tool reference for the Ahrefs MCP connector. Use this skill whenever the user asks to fetch SEO data, backlink data, keyword research, SERP analysis, competitor analysis, site audits, or web analytics via Ahrefs. Also use when the user asks to "use Ahrefs", "check Ahrefs", or run any Ahrefs-related query.

Ahrefs MCP Skill

Connection Config

Endpoint: https://api.ahrefs.com/mcp/mcp
Transport: Streamable HTTP (MCP Protocol 2025-06-18)
Auth: Authorization: Bearer <TOKEN> header
Token: stored in references/config.md
Server name in manus-mcp-cli: ahrefs (but see caveat below)

Important: manus-mcp-cli tool list/call --server ahrefs returns a 401 error because the Manus connector proxy does not forward the Bearer token correctly. Always call the Ahrefs MCP endpoint directly via HTTP using the Python helper below.

Quick-Start

Use the reusable client at scripts/ahrefs_client.py:

import sys
sys.path.insert(0, '/home/ubuntu/skills/ahrefs-mcp/scripts')
from ahrefs_client import call_tool

result = call_tool("site-explorer-domain-rating", {
    "target": "example.com",
    "date": "2025-01-01"
})
print(result)

Or run standalone: python /home/ubuntu/skills/ahrefs-mcp/scripts/ahrefs_client.py

Critical Usage Rules

Call doc first before using a new tool — the tools/list schema is a stub; real required fields and valid select columns are only in doc.
Most tools require date in YYYY-MM-DD format even when not listed as required.
Monetary values (org_cost, paid_cost, cpc, traffic_value) are in USD cents — divide by 100 for USD.
Use mode=subdomains when analyzing a full domain. mode=domain excludes www and subdomains.
select columns vary per tool — if you get a "column not found" error, call doc for exact available columns.

Tool Categories (95 tools total)

Category	Count	Key Tools
Site Explorer	24	`site-explorer-metrics`, `site-explorer-domain-rating`, `site-explorer-backlinks-stats`, `site-explorer-organic-keywords`, `site-explorer-top-pages`, `site-explorer-referring-domains`, `site-explorer-organic-competitors`, `site-explorer-refdomains-history`
Web Analytics	34	`web-analytics-stats`, `web-analytics-chart`, `web-analytics-countries`, `web-analytics-top-pages`, `web-analytics-sources`, `web-analytics-devices`
Keywords Explorer	6	`keywords-explorer-overview`, `keywords-explorer-matching-terms`, `keywords-explorer-related-terms`, `keywords-explorer-search-suggestions`, `keywords-explorer-volume-by-country`, `keywords-explorer-volume-history`
Brand Radar	9	`brand-radar-mentions-overview`, `brand-radar-sov-overview`, `brand-radar-cited-domains`, `brand-radar-ai-responses`
Site Audit	3	`site-audit-projects`, `site-audit-issues`, `site-audit-page-explorer`
Rank Tracker	5	`rank-tracker-overview`, `rank-tracker-serp-overview`, `rank-tracker-competitors-overview`
Management	5	`management-projects`, `management-project-keywords`, `management-project-competitors`
Batch Analysis	1	`batch-analysis` (up to 100 targets simultaneously)
SERP Overview	1	`serp-overview`
Subscription	1	`subscription-info-limits-and-usage`

Common Patterns

Domain overview:

call_tool("site-explorer-metrics", {"target": "domain.com", "mode": "subdomains", "protocol": "both", "date": "2025-01-01"})

Keyword research:

call_tool("keywords-explorer-matching-terms", {"keywords": ["your keyword"], "country": "us", "select": "keyword,volume,difficulty,cpc", "limit": 20, "order_by": "volume:desc"})

Batch domain comparison:

call_tool("batch-analysis", {
    "select": ["domain_rating", "org_traffic", "backlinks", "refdomains", "org_keywords"],
    "targets": [
        {"url": "domain1.com", "mode": "subdomains", "protocol": "both"},
        {"url": "domain2.com", "mode": "subdomains", "protocol": "both"},
    ]
})

SERP analysis:

call_tool("serp-overview", {"keyword": "target keyword", "country": "us", "select": "url,title,position,traffic,domain_rating,backlinks"})

Top organic keywords for a site:

call_tool("site-explorer-organic-keywords", {"target": "domain.com", "mode": "subdomains", "protocol": "both", "country": "us", "date": "2025-01-01", "select": "keyword,volume,best_position,sum_traffic", "limit": 20, "order_by": "sum_traffic:desc"})

Reference Files

references/config.md — API token and account details
references/tool_catalog.md — Full list of all 95 tools with descriptions