Ahrefs

Two jobs: quick lookups for any domain, and staged keyword research. Every Ahrefs call spends API units from the plan, so both keep a log of what was spent. Setup: connections/ahrefs-mcp.md, or run the connect skill.

Two ways in, and they are not interchangeable:

• The Ahrefs MCP server (default, any paid plan from Lite). Tools are named mcp__ahrefs__*. The agent calls them. Do not write scripts against the MCP endpoint: Ahrefs' terms do not permit custom scripts, bridges or standalone JSON-RPC clients there.
• API v3 with AHREFS_API_KEY (an API v3 key; Ahrefs lists "direct access to API v3" from the Lite plan up, checked 2026-10-21; generate it under Account settings → API keys). Scripts use it: https://api.ahrefs.com/v3/<path>, Authorization: Bearer <key>. An MCP key on API v3, or an API key on MCP, returns 401.

The key is read from the environment first, then from ~/.config/marketing-agent-kit/.env (or MARKETING_KIT_ENV).

Mode 1: quick lookups (any domain)

Use the MCP tools. If they are not loaded, search for them (for example "ahrefs organic keywords"); if the server is not connected, send the user to connections/ahrefs-mcp.md. Server rules:

• Call the doc tool before the first use of any tool.
• Every money value is in USD cents. Divide by 100.
• If a response carries render_with metadata, call that render tool with the data.
• Save what you will quote: write each response to raw/seo/<name>.json next to the analysis.

With an API v3 key, the same calls work from the script (repeatable, saved, units logged):

python3 ${CLAUDE_SKILL_DIR}/scripts/ahrefs_api.py site-explorer-organic-keywords target=example.com date=2026-09-30 \
    select=keyword,sum_traffic,best_position limit=100 order_by=sum_traffic:desc --out raw/seo/kw.json
python3 ${CLAUDE_SKILL_DIR}/scripts/ahrefs_api.py subscription-info-limits-and-usage      # units left (free)
python3 ${CLAUDE_SKILL_DIR}/scripts/ahrefs_api.py endpoints site-explorer                 # list endpoints (no key, no units)
python3 ${CLAUDE_SKILL_DIR}/scripts/ahrefs_api.py params site-explorer/top-pages          # one endpoint's parameters

The script takes an API path or an MCP tool name. A tool name becomes <group>/<rest> (site-explorer-top-pages → site-explorer/top-pages) with a few exceptions it knows: serp-overview → serp-overview/serp-overview, batch-analysis → batch-analysis/batch-analysis, site-explorer-referring-domains → site-explorer/refdomains, site-explorer-linked-domains → site-explorer/linkeddomains. doc, render-* and the *-entities tools exist only in MCP. Each call prints its units (response header x-api-units-cost-total-actual) and appends them to ~/.local/share/marketing-agent-kit/seo/ahrefs_units.jsonl (override with AHREFS_UNITS_LOG).

Rules: limit<=150 by default. Never pull raw backlinks by the thousand: site-explorer-all-backlinks is the most expensive tool; start with stats and referring domains. Check units left before a long series of calls. Numbers in a report must be checkable against the saved raw files. Do not use Ahrefs paid-traffic or ad-budget estimates in reports: they are systematically wrong. Saying that a domain has paid keywords is fine; dollar figures are not. Ad libraries do not disclose budgets either.

Mode 2: keyword research (staged)

scripts/kw.py STAGE --project <name> [--country xx], one project per topic and market. It reads the site config ~/.config/marketing-agent-kit/seo/<site>.toml ([keywords]: default country, markets, optional monthly unit cap; [site] hosts to find your own pages in SERPs; format in ../gsc-insights/references/config.md). For the GSC join, run gsc-insights' gsc_pull.py first. Project files live in <data>/keywords/<project>/.

Use --dry-run on price and serp first. Answers are cached in <data>/ahrefs_cache.sqlite (30 days, SERPs 14); units go to <data>/ahrefs_units.jsonl. The monthly cap ([keywords] monthly_unit_cap, 0 = log only) is checked before each call, across parallel runs.

Transport A: API v3 (--via api)

With AHREFS_API_KEY set, discover, price and serp call API v3 themselves. Units come from the x-api-units-cost-total-actual response header; a call without that header is logged with units_unreported. A 429 (60 requests per minute by default) is retried once after Retry-After.

Transport B: the MCP tools (--via mcp, the default without an API key)

Most plans have MCP access and no API v3 key. Then the stages do the bookkeeping and you make the calls:

1. Run the stage, e.g. kw.py price --project de-dubbing --country de. It applies every answer already in the cache, writes the calls still needed to <project>/mcp_plan.json and prints them with ids (price-001 …).
2. For each planned call, one at a time (parallel calls fail): call the MCP tool (mcp__ahrefs__<tool>) with exactly the planned arguments and save its output to a file. Keep both text blocks if there are two: the second one, apiUsageCosts, holds the real unit cost. If Claude Code already saved a long output to a file, use that file.
3. kw.py import --project de-dubbing --call price-001 <file>. Import checks the rows, caches them under the same key the API path uses, updates the project files and logs the units (from apiUsageCosts, or the documented estimate marked units_estimated when the file has none). Importing the same file twice does nothing.
4. Re-run the stage: with every answer cached it plans nothing and you go on to the next stage.

For a call that is not in the plan, pass --tool keywords-explorer-overview --args '<the JSON arguments you sent>' instead of --call, or save a wrapper {"tool": …, "arguments": {…}, "result": <output>}. If a pricing call fails with an internal server error, one keyword in the batch is one Ahrefs has never indexed: re-run price --batch 1 for the rest and skip the keyword that fails alone. cluster, prioritize and budget are the same for both transports. budget without an API key shows the logged units; ask the free MCP tool subscription-info-limits-and-usage for the account's limits.

Workflow and decision rules

Agree topic, market and language; research each language natively (seeds in the market's language; --from-gsc shows how people there phrase it); discover → read candidates → price (dry run first) → serp for the top 30–60 → cluster → prioritize; check the SERPs of the top clusters yourself before recommending.

• SERP page type decides the format: articles → an article can rank; landing/product pages → a landing page; app stores or vendor homepages → usually skip.
• Existing page first: if you rank 4–20 for the cluster in GSC, improve that page.
• One cluster, one page. Do not split keywords that share a SERP.
• AI Overview present → fewer clicks at the same position; commercial queries get AIOs too.
• Metrics are estimates; KD is often missing for small non-English keywords. Calibrate with GSC impressions.
• score = volume × (1 − KD/100) × (1.0 commercial, 0.5 informational) ranks clusters; it does not forecast traffic.
• Never present a keyword list as research without the SERP check.

Unit costs

Read references/unit-costs.md before pricing more than a few dozen keywords. The short version: cost per call = max(50, per-row cost × rows); volume-type fields (volume, global_volume, difficulty, traffic_potential, parent_volume, intents) cost about 10 units per row each, keyword about 1. Discover with select=keyword first, then price only the shortlist; put the volume floor into where (only kept rows are billed); send pricing calls sequentially.

Adapt it

• Put your own domains, hosts and markets into the site config ([site] hosts, [keywords] default_country, markets) so SERPs mark your pages and --from-gsc uses your queries.
• Set [keywords] monthly_unit_cap to the share of the plan's units that keyword research may spend, and put a cap on the Ahrefs key itself (Account settings → API keys).
• Keep a domains.json with your domain and your usual competitors, so "compare us with the usual three" needs no lookups.
• Change the action rules in kw.py (action()) and the score weights if your business values informational content differently.
• If you run the same SEO snapshot every month, turn the lookups into a fixed ahrefs_api.py script (API v3) and keep the agent for interpreting the changes.