Ahrefs MCP Server

MCP server per Ahrefs API v3 (Site Explorer), pensato per il piano Lite (10.000 units/mese, 60 req/min).

Espone 5 tool a Claude Code via il mcp-gateway esistente, con caching SQLite e budget tracking per non sforare la quota.

Tool disponibili

Tool	Endpoint	Costo (units)	Cache TTL
ahrefs_domain_rating	/site-explorer/domain-rating	~50	7 giorni
ahrefs_backlinks_stats	/site-explorer/backlinks-stats	~50	7 giorni
ahrefs_top_organic_keywords	/site-explorer/organic-keywords	50 + limit×4 (~130 a limit=20)	24h
ahrefs_top_pages	/site-explorer/top-pages	50 + limit×3 (base) o 50 + limit×12 (con traffic)	24h
ahrefs_budget_status	(locale)	0	—

Quanto puoi usarlo col piano Lite

10.000 units/mese a budget pieno significa:

• ~200 chiamate di solo domain_rating o backlinks_stats, oppure
• ~90 chiamate di top_organic_keywords (limit=20), oppure
• ~110 top_pages senza traffic (limit=20), oppure
• ~34 top_pages con with_traffic=True (limit=20).

Mix realistico mensile: ~150–250 chiamate utili sfruttando la cache (TTL 7 giorni per metriche stabili, 24h per liste ranked). Usa ahrefs_budget_status per verificare il consumo in qualsiasi momento.

Quickstart locale (sviluppo)

cd "/mnt/d/NAS/Claude/MCP Ahrefs"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# inserisci AHREFS_API_KEY=...
# (per dev locale puoi puntare cache/budget alla cartella corrente)
echo "AHREFS_CACHE_DB_PATH=./cache.db" >> .env
echo "AHREFS_BUDGET_PATH=./budget.json" >> .env

python ahrefs_server.py
# in altra shell
curl http://localhost:8089/

Smoke test API key

Prima di tutto verifica che la tua chiave Lite funzioni:

export AHREFS_API_KEY="..."
curl -s -i -H "Authorization: Bearer $AHREFS_API_KEY" \
  "https://api.ahrefs.com/v3/site-explorer/domain-rating?date=$(date +%F)&target=calcolatorigratis.com%2F"

Cerca nei response header le righe X-Api-Units-Cost e X-Api-Units-Remaining — confermano i nomi reali per il client (sono parsati case-insensitive con fallback graceful).

Deploy su Proxmox CT102

./deploy/install.sh root@ct102
ssh root@ct102 'nano /opt/ahrefs-mcp/.env'   # imposta AHREFS_API_KEY
ssh root@ct102 'systemctl restart ahrefs-mcp'
ssh root@ct102 'journalctl -u ahrefs-mcp -f'

Lo script:

• rsync del progetto in /opt/ahrefs-mcp
• crea /var/lib/ahrefs-mcp per cache.db e budget.json
• venv + pip install
• copia il systemd unit + abilita + restart

Integrazione con mcp-gateway

Sul container che ospita il gateway (CT102), aggiungi ahrefs-mcp come upstream con tag ahrefs:

• URL upstream: http://localhost:8089/sse
• Tag: ahrefs (o ahrefs,seo)
• Restart mcp-gateway

Per accesso cross-sessione Claude Code, aggiorna ~/.claude.json:

{
  "mcpServers": {
    "mcp-gateway": {
      "type": "http",
      "url": "https://mcp.calcolatorigratis.com/mcp?tags=core,monetizzazione,ahrefs",
      "headers": { "Authorization": "Bearer <gateway-token>" }
    }
  }
}

Oppure per i singoli progetti aggiorna i loro .mcp.json.

Struttura

ahrefs_server.py    # FastMCP + Starlette + uvicorn (port 8089)
ahrefs_tools.py     # 5 @mcp_server.tool()
ahrefs_client.py    # httpx wrapper + parsing X-Api-Units-*
ahrefs_cache.py     # SQLite TTL cache
ahrefs_budget.py    # Tracker units mensile (warning 8K, hard stop 10K)
deploy/
  ahrefs-mcp.service
  install.sh
.env.example
requirements.txt

Note operative

• Hard stop a 10.000 units: il MCP rifiuta nuove chiamate API (le cache hit continuano a funzionare). Reset automatico al cambio mese.
• Warning a 8.000 units: appende un suffisso ⚠️ alle risposte ma non blocca.
• with_traffic=True su top_pages: usalo solo quando ti serve davvero, costa ~3x.
• Cache deterministica: chiave = SHA256(endpoint + params ordinati). Stesso target+date+limit ⇒ stessa chiave.