Imported from joelhooks/joelclaw (skills/ahrefs/SKILL.md). Install upstream with npx skills add joelhooks/joelclaw --skill ahrefs. Copyright stays with the author.

Ahrefs SEO Tools

Query Ahrefs via their remote MCP server (Streamable HTTP transport). Joel has a Standard plan ($249/mo).

Connection

Endpoint: https://api.ahrefs.com/mcp/mcp Auth: Bearer token via agent-secrets lease ahrefs_api_key Transport: Streamable HTTP (JSON-RPC over POST, NOT SSE) Config: ~/.pi/agent/mcp.json under ahrefs key

Raw curl pattern (when MCP bridge isn't available)

AHREFS_KEY=$(agent-secrets lease ahrefs_api_key --ttl 4h --json 2>&1 | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['value'])")

curl -s -X POST "https://api.ahrefs.com/mcp/mcp" \
  -H "Authorization: Bearer $AHREFS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc":"2.0","id":1,"method":"tools/call",
    "params":{"name":"TOOL_NAME","arguments":{...}}
  }'

MCP initialization handshake (required once per session)

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{
  "protocolVersion":"2025-03-26",
  "capabilities":{},
  "clientInfo":{"name":"pi","version":"1.0"}
}}

Critical: Use doc tool first

Before calling any data tool for the first time, call the doc tool to get the real input schema:

{"name":"doc","arguments":{"tool":"keywords-explorer-overview"}}

This returns the full schema with field names, types, filter syntax, and output columns. The tool list schemas are summaries — doc gives the real contract.

API Units

Every call costs API units. The response includes cost info:

{"apiUsageCosts":{"rows":10,"units-cost-row":21,"units-cost-total":210}}

• Monetary values (CPC, traffic_value, etc.) are in USD cents, not dollars. Divide by 100.
• difficulty costs 10 extra units per row when selected
• Standard plan has monthly unit limits — check with subscription-info-limits-and-usage

Tool Categories

Keywords Explorer (keyword research)

Common select fields: keyword, volume, difficulty, cpc, traffic_potential, global_volume, parent_topic, intents, clicks, cps, serp_features

Gotcha: keywords-explorer-overview requires keywords as an array BUT returns empty results for broad terms — it only returns data for exact keyword matches in their DB. Use matching-terms or search-suggestions for discovery.

Site Explorer (domain/URL analysis)

target = domain (example.com), URL (https://example.com/page), or path (example.com/blog/*) mode = exact | domain | subdomains | prefix date = YYYY-MM-DD (use recent date like today)

SERP Analysis

Batch Analysis

Rank Tracker (requires project setup in Ahrefs UI)

Tools: rank-tracker-overview, rank-tracker-competitors-*, rank-tracker-serp-overview All require project_id — get via management-projects.

Site Audit (requires project setup in Ahrefs UI)

Tools: site-audit-issues, site-audit-page-explorer, site-audit-page-content, site-audit-projects

Brand Radar (AI visibility monitoring)

Tools: brand-radar-mentions-*, brand-radar-impressions-*, brand-radar-sov-*, brand-radar-ai-responses, brand-radar-cited-* Requires brand monitoring setup in Ahrefs UI.

Web Analytics (requires Ahrefs analytics snippet)

All web-analytics-* tools require project_id from a Web Analytics project.

Management

Common Recipes

Keyword research for a local service

# 1. Discover keywords
{"name":"keywords-explorer-matching-terms","arguments":{
  "keywords":["water damage restoration"],
  "select":"keyword,volume,difficulty,cpc,traffic_potential",
  "country":"us",
  "limit":20,
  "order_by":"volume:desc"
}}

# 2. Check specific local terms
{"name":"keywords-explorer-overview","arguments":{
  "keywords":["water damage restoration vancouver wa","water damage portland or"],
  "select":"keyword,volume,difficulty,cpc",
  "country":"us"
}}

Competitor analysis

# 1. Get domain metrics
{"name":"site-explorer-metrics","arguments":{
  "target":"competitor.com",
  "date":"2026-03-11"
}}

# 2. See what they rank for
{"name":"site-explorer-organic-keywords","arguments":{
  "select":"keyword,position,volume,traffic,url",
  "target":"competitor.com",
  "date":"2026-03-11",
  "country":"us",
  "limit":20,
  "order_by":"traffic:desc"
}}

# 3. Find their competitors
{"name":"site-explorer-organic-competitors","arguments":{
  "select":"domain,common_keywords,keywords_unique_to_target",
  "target":"competitor.com",
  "country":"us",
  "date":"2026-03-11",
  "limit":10
}}

Batch compare multiple domains

{"name":"batch-analysis","arguments":{
  "select":"target,domain_rating,organic_traffic,organic_keywords",
  "targets":["site1.com","site2.com","site3.com"],
  "country":"us"
}}

Check API budget

{"name":"subscription-info-limits-and-usage","arguments":{}}

Filter Syntax

The where parameter uses a JSON filter expression:

{"field":"volume","is":["gte",100]}

Operators: eq, neq, gt, gte, lt, lte, substring, isubstring, prefix, suffix, regex

Boolean combinators: and, or, not

{"and":[
  {"field":"volume","is":["gte",100]},
  {"field":"difficulty","is":["lte",30]}
]}

MCP Config (correct)

The ~/.pi/agent/mcp.json entry should use the remote URL, not the npm package:

{
  "ahrefs": {
    "url": "https://api.ahrefs.com/mcp/mcp",
    "headers": {
      "Authorization": "Bearer <from agent-secrets>"
    },
    "lifecycle": "lazy"
  }
}

NOT the npx command — that was the wrong setup. The npm @ahrefs/mcp package does NOT work with Standard plan auth. The remote endpoint does.

Gotchas

1. Empty results from keywords-explorer-overview: This tool returns data only for keywords that exist exactly in Ahrefs' DB. Use matching-terms for discovery, overview for metrics on known keywords.
2. CPC is in cents: A CPC of 190 = $1.90
3. difficulty costs extra units: 10 units per row when included in select
4. Date format: Always YYYY-MM-DD
5. Country codes: Use ISO 2-letter codes (us, gb, au, etc.)
6. The doc tool is your friend: Always call it before using a new tool to get the real schema
7. http+sse is not supported: The server explicitly rejects SSE. Use POST-based Streamable HTTP only.