Backlink Outreach MCP Server

Server MCP per la discovery e outreach automatizzata di backlink per calcolatorigratis.com.

Stack: Python 3 + FastMCP + SQLite + httpx
Deploy: CT102 Proxmox (192.168.1.107:8010)
Tunnel: https://backlink.calcolatorigratis.com
Dashboard: https://backlink.calcolatorigratis.com/dashboard

---

Come ottenere le API Key

Il server utilizza 4 chiavi API esterne. Tutte hanno un free tier sufficiente per l'uso del progetto. Le chiavi si inseriscono direttamente dalla dashboard (sezione "Chiavi API" in fondo alla pagina) oppure nel file .env.

Le chiavi salvate dalla dashboard hanno priorita su quelle nel .env.

---

1. Google Custom Search API Key + Engine ID (CX)

Permette di cercare su Google via API ufficiale (100 query/giorno gratis) invece dello scraping HTML.

Stato aprile 2026: La Custom Search JSON API ha due limitazioni importanti:

• Chiusa ai nuovi clienti — se il tuo account Google Cloud non ha mai abilitato questa API, potresti ricevere errore 403. Gli account esistenti possono usarla fino al 1 gennaio 2027.
• "Ricerca in tutto il Web" deprecata — l'opzione per cercare su tutto il web non e piu attivabile. Il motore di ricerca cerca SOLO nei siti/domini che aggiungi manualmente (max 50 domini).

Cosa significa in pratica: La CSE resta utile per cercare in un set di domini italiani noti (blog, directory, portali), ma non puo sostituire una ricerca web generica. Per la discovery generica, il server usa lo scraping HTML (20 query/giorno) oppure GSC/Ahrefs MCP.

Se non riesci ad attivarla, salta questa sezione. Il server funziona perfettamente senza.

Passo 1 — Crea un progetto Google Cloud

1. Vai su Google Cloud Console
2. Accedi con il tuo account Google
3. Clicca il menu a tendina dei progetti in alto
4. Clicca Nuovo progetto
5. Nome: Backlink Outreach (o qualsiasi nome)
6. Clicca Crea

Passo 2 — Abilita la Custom Search API

1. Nel progetto appena creato, vai su API e servizi > Libreria
   • URL diretto: https://console.cloud.google.com/apis/library
2. Cerca "Custom Search API"
3. Clicca sul risultato "Custom Search JSON API"
4. Clicca Abilita
   • Se ricevi errore 403 "PERMISSION_DENIED", il tuo account non ha accesso (API chiusa ai nuovi clienti). Salta questa sezione.

Passo 3 — Genera la API Key

1. Vai su API e servizi > Credenziali
   • URL diretto: https://console.cloud.google.com/apis/credentials
2. Clicca + Crea credenziali > Chiave API
3. Copia la chiave generata (formato: AIzaSy...)
4. (Consigliato) Clicca Limita chiave e seleziona solo "Custom Search JSON API"

Questa e la tua GOOGLE_CSE_API_KEY. Serve anche per Google PageSpeed Insights (il server la riusa automaticamente).

Passo 4 — Crea il Search Engine e ottieni il CX

1. Vai su Programmable Search Engine

2. Nome del motore di ricerca: Backlink Discovery

3. Siti in cui eseguire ricerche: aggiungi i domini target per la discovery backlink. Esempi di pattern utili per il mercato italiano:

   *.blogspot.com/*
   *.wordpress.com/*
   *.altervista.org/*
   *.medium.com/*
   *.substack.com/*
   

   Puoi aggiungere fino a 50 domini distinti. Aggiungi i portali, blog e directory italiane dove vuoi cercare prospect per backlink. Potrai modificarli in seguito.

4. Clicca Crea

5. Dopo la creazione, clicca Personalizza per aprire il pannello di configurazione

6. Nella pagina Impostazioni base, trova l'ID motore di ricerca (Search engine ID)

   • E una stringa tipo a1b2c3d4e5f6g7h8i (17 caratteri alfanumerici)

Questo e il tuo GOOGLE_CSE_CX.

Nota: L'opzione "Ricerca in tutto il Web" nella sezione "Funzionalita dei risultati di ricerca" e deprecata e non puo piu essere attivata. Il motore cerchera solo nei domini che hai inserito. Per una ricerca web generica, usa il tool search_google_prospects senza CSE (scraping HTML) oppure i tool GSC/Ahrefs MCP.

Riepilogo

Chiave	Dove trovarla	Free tier
GOOGLE_CSE_API_KEY	Google Cloud Console > Credenziali	100 query/giorno
GOOGLE_CSE_CX	Programmable Search Engine > Panoramica	Incluso

Riferimenti:

• Documentazione ufficiale Custom Search JSON API
• Panoramica e limiti
• Pannello Programmable Search Engine

---

2. Hunter.io API Key

Permette di trovare email associate a un dominio (25 ricerche/mese gratis) e verificarle (50 verifiche/mese). Il server funziona anche senza questa chiave (usa solo lo scraping HTML per cercare email visibili nelle pagine).

Passo 1 — Registrati

1. Vai su Hunter.io
2. Clicca Sign up in alto a destra
3. Registrati con email e password, oppure con Google/LinkedIn
4. Conferma l'email di verifica

Passo 2 — Ottieni la API Key

1. Dopo il login, vai su API Keys
   • Oppure: clicca il tuo avatar > API nel menu
2. La chiave API e visibile nella pagina
   • Formato: stringa alfanumerica lunga ~40 caratteri
3. Copia la chiave

Questa e la tua HUNTER_API_KEY.

Passo 3 — Verifica il funzionamento (opzionale)

Puoi testare la chiave direttamente nel terminale:

curl "https://api.hunter.io/v2/account?api_key=LA_TUA_CHIAVE"

Se funziona, vedrai il tuo piano e le ricerche rimanenti.

Free tier

Risorsa	Limite mensile
Domain Search (ricerca email per dominio)	25 ricerche
Email Verifier (verifica deliverability)	50 verifiche
Email Finder (trova email per nome+dominio)	25 ricerche

Autenticazione

La chiave puo essere passata in 3 modi (il server usa il primo):

• Parametro query: ?api_key=LA_TUA_CHIAVE
• Header: X-API-KEY: LA_TUA_CHIAVE
• Header: Authorization: Bearer LA_TUA_CHIAVE

Riferimenti:

• Panoramica API Hunter.io
• Documentazione API v2
• Gestione API Keys

---

3. Open PageRank API Key

Fornisce il PageRank (0-10) e il ranking globale dei domini. Usato per lo scoring automatico dei prospect. Il server funziona anche senza questa chiave (lo score resta manuale).

Passo 1 — Registrati

1. Vai su Open PageRank Signup
2. Inserisci nome, email e password
3. Clicca Sign Up
4. Conferma l'email di verifica

Passo 2 — Ottieni la API Key

1. Dopo il login, vai su Open PageRank Dashboard
2. La API key e visibile nella dashboard principale
   • Formato: stringa alfanumerica ~40 caratteri
3. Copia la chiave

Questa e la tua OPENPAGERANK_API_KEY.

Passo 3 — Verifica il funzionamento (opzionale)

curl -H "API-OPR: LA_TUA_CHIAVE" "https://openpagerank.com/api/v1.0/getPageRank?domains[]=google.com"

Se funziona, vedrai il PageRank di google.com (dovrebbe essere ~10).

Free tier

Risorsa	Limite
Richieste API	10.000/ora
Domini per richiesta (batch)	fino a 100
Costo	Gratuito, nessun piano a pagamento richiesto

Autenticazione

La chiave va passata nell'header HTTP:

API-OPR: LA_TUA_CHIAVE

Riferimenti:

• Homepage Open PageRank
• Documentazione API
• Pagina registrazione

---

Inserire le chiavi

Metodo 1 — Dashboard (consigliato)

1. Apri la dashboard: https://backlink.calcolatorigratis.com/dashboard
2. Scorri fino alla sezione "Chiavi API" in fondo
3. Per ogni chiave:
   • Incolla il valore nel campo di testo
   • Clicca Salva
   • Clicca Test per verificare che funzioni
4. Le chiavi salvate dalla dashboard sono attive immediatamente (nessun restart necessario)

Metodo 2 — File .env

Modifica il file .env nella cartella del progetto:

GOOGLE_CSE_API_KEY=AIzaSy...
GOOGLE_CSE_CX=a1b2c3d4e5f6g7h8i
HUNTER_API_KEY=abc123...
OPENPAGERANK_API_KEY=xyz789...

Dopo la modifica, rideploya con bash deploy.sh per applicare le modifiche.

Le chiavi inserite dalla dashboard hanno priorita su quelle nel .env.

---

Riepilogo tempi di registrazione

API	Tempo	Difficolta	Note
Open PageRank	~2 minuti	Facile	Solo email + password
Hunter.io	~2 minuti	Facile	Solo email + password
Google CSE	~5 minuti	Media	Richiede progetto Google Cloud

---

API gratuite aggiuntive (nessuna chiave richiesta)

Il server usa anche queste API che non richiedono registrazione:

API	Cosa fa	Limite
Tranco List	Ranking dominio top-1M	Illimitato
Wayback Machine CDX	Eta dominio (prima archiviazione)	~15 req/min
RDAP	WHOIS dominio (registrazione, scadenza)	~100 req/ora
Google PageSpeed Insights	Score performance/SEO	25.000/giorno

---

Struttura file

backlink_server.py      — Server ASGI + dashboard + API endpoints
backlink_tools.py       — 20 tool MCP
database.py             — SQLite schema + helpers
google_search.py        — Google CSE API + scraping fallback
domain_metrics.py       — Open PageRank + Tranco + Wayback + RDAP
email_discovery.py      — Hunter.io email finder
tech_detection.py       — CMS detection + PageSpeed Insights
email_client.py         — SMTP/IMAP (Hostinger)
deploy.sh               — Deploy automatico su CT102
.env                    — Configurazione produzione