Joelclaw ahrefs

Query Ahrefs SEO data via their MCP server — keyword research, site explorer, SERP analysis, competitor research, backlink analysis, and Brand Radar AI visibility. Use when researching keywords, analyzing competitors, checking backlinks, auditing sites, or any SEO data task. Triggers on 'keyword research', 'check backlinks', 'competitor analysis', 'ahrefs', 'search volume', 'keyword difficulty', 'domain rating', 'SERP analysis', 'SEO data', 'brand radar', or any request needing search engine optimization data.

install

source · Clone the upstream repo

git clone https://github.com/joelhooks/joelclaw

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/joelhooks/joelclaw "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ahrefs" ~/.claude/skills/joelhooks-joelclaw-ahrefs && rm -rf "$T"

manifest: skills/ahrefs/SKILL.md

source content

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)

Tool	Use for	Key required params
`keywords-explorer-overview`	Volume, KD, CPC for specific keywords	`select` , `country` , `keywords` (array)
`keywords-explorer-matching-terms`	Find keyword ideas matching seed terms	`select` , `country` , `keywords` , `limit` , `order_by`
`keywords-explorer-related-terms`	"Also rank for" and "also talk about"	`select` , `country` , `keywords`
`keywords-explorer-search-suggestions`	Autocomplete suggestions with metrics	`select` , `country` , `keywords`
`keywords-explorer-volume-history`	Historical volume trends	`country` , `keyword` (singular)
`keywords-explorer-volume-by-country`	Volume broken down by country	`keyword` (singular)

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

search-suggestions

for discovery.

Site Explorer (domain/URL analysis)

Tool	Use for	Key required params
`site-explorer-metrics`	DR, traffic, keywords count	`target` , `date`
`site-explorer-organic-keywords`	What keywords a site ranks for	`select` , `target` , `date` , `country`
`site-explorer-organic-competitors`	Who competes in organic search	`select` , `target` , `country` , `date`
`site-explorer-top-pages`	Best pages by traffic	`select` , `target` , `date`
`site-explorer-all-backlinks`	Inbound link details	`select` , `target`
`site-explorer-referring-domains`	Domains linking to target	`select` , `target`
`site-explorer-domain-rating`	DR score	`target` , `date`
`site-explorer-domain-rating-history`	DR over time	`target` , `date_from`
`site-explorer-backlinks-stats`	Backlink summary stats	`target` , `date`
`site-explorer-anchors`	Anchor text analysis	`select` , `target`
`site-explorer-broken-backlinks`	Broken inbound links	`select` , `target`
`site-explorer-metrics-by-country`	Traffic by country	`target` , `date`
`site-explorer-metrics-history`	Historical traffic/keywords	`target` , `date_from`

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

Tool Use for Key required params

serp-overview

Batch Analysis

Tool Use for Key required params

batch-analysis

Analyze multiple URLs/domains at once

select

targets

(array)

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

Tool	Use for
`management-projects`	List all projects
`management-project-keywords`	Keywords in a project
`management-project-competitors`	Competitors in a project
`management-locations`	Location IDs for targeting
`management-keyword-list-keywords`	Keywords from a saved list (free, no units)
`subscription-info-limits-and-usage`	Check remaining API units

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

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.
CPC is in cents: A CPC of
```
190
```
= $1.90
difficulty
costs extra units: 10 units per row when included in
```
select
```
Date format: Always
```
YYYY-MM-DD
```
Country codes: Use ISO 2-letter codes (
```
us
```
,
```
gb
```
,
```
au
```
, etc.)
The
doc
tool is your friend: Always call it before using a new tool to get the real schema
http+sse is not supported
: The server explicitly rejects SSE. Use POST-based Streamable HTTP only.