Uso Claude Code praticamente ogni giorno. Ci scrivo codice, ci ragiono su architetture, ci analizzo problemi — è diventato parte integrante del mio flusso di lavoro. Quando Anthropic ha rilasciato il Model Context Protocol — la possibilità per Claude di usare strumenti esterni in tempo reale — ho capito subito il potenziale.
Mi capita spesso, sia per progetti personali che per clienti, di utilizzare tool per la SEO. Ultimamente sto usando molto SEOZoom.
Il problema: troppi tab, troppo context-switch
Chi fa SEO lo sa. Stai analizzando un sito, hai Claude aperto in una finestra, SEOZoom in un'altra, un foglio di calcolo in una terza. Copi keyword, incolli metriche, torni su Claude a chiedere "che ne pensi di questi dati?", ricopii la risposta nel report.
Il flusso funziona, ma è lento. Ogni cambio di finestra è un'interruzione. Ogni copia-incolla è un punto dove si perde contesto.
E se Claude potesse interrogare SEOZoom direttamente?
Ho cercato un server MCP per SEOZoom — non esisteva. Così l'ho costruito.
Il risultato è un progetto open-source, snello, sviluppato in una notte e ancora alla sua prima versione — ma già funzionante e utile.
MCP: quando l'AI smette di indovinare e inizia a leggere i dati
Il Model Context Protocol (MCP) è uno standard aperto creato da Anthropic che permette ai modelli di linguaggio di usare strumenti esterni. Non è un plugin, non è un'estensione proprietaria — è un protocollo di comunicazione basato su JSON-RPC che funziona su qualsiasi client compatibile.
L'idea è semplice: invece di incollare dati nella chat e chiedere "analizza questo", l'LLM chiama direttamente il tool, riceve il JSON di risposta e lo interpreta in autonomia. Nessun copia-incolla, nessuna perdita di contesto.
Un server MCP è un processo che espone dei "tool" (funzioni tipate con parametri e descrizioni). Il client MCP (Claude Desktop, Claude Code, Cursor) lancia il server, scopre quali tool offre e li rende disponibili al modello. Quando Claude decide che serve un dato — ad esempio il volume di ricerca di una keyword — chiama il tool corrispondente. Tutto avviene in modo trasparente, nel mezzo della conversazione.
SEOZoom MCP Server: 25 tool pronti all'uso
SEOZoom MCP Server è il server MCP che ho sviluppato per portare le API di SEOZoom dentro Claude. È scritto in Python, è open-source e supporta 25 operazioni suddivise in cinque categorie:
- Keywords (4 tool) — metriche, SERP attuale, SERP storica, keyword correlate
- Domains (8 tool) — metriche, authority, nicchie, pagine migliori, keyword posizionate, competitor, AI Overview
- URLs (4 tool) — PZA, metriche, keyword per URL, intent gap
- Projects (8 tool) — lista progetti, overview, keyword, pagine migliori, pagine con potenziale, winner/loser
- Utility (1 tool) — controllo unità API residue
Non serve specificare quale tool usare. Claude lo sceglie da solo, in base alla domanda:
"Quali sono le metriche per la keyword regime forfettario?"
"Analizza il dominio corriere.it"
"Chi sono i competitor organici di aranzulla.it?"
"Per quali keyword il mio dominio appare nelle AI Overview di Google?"
"Mostrami le keyword monitorate del mio progetto e quali stanno perdendo posizioni"
"Quante unità API mi restano?"
Claude seleziona i tool giusti, li chiama in sequenza, incrocia i dati e presenta un'analisi strutturata — tutto in una sola interazione.
Due modalità: remoto o locale
Il progetto offre due modalità di utilizzo, pensate per esigenze diverse.
Server remoto (Lite)
La via più veloce. Il server è già online su Koyeb — basta aggiungere una URL nella configurazione del proprio client MCP:
{
"mcpServers": {
"seozoom": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://fresh-chiquita-sozione-22beccd8.koyeb.app/mcp?api_key=LA-TUA-API-KEY"
]
}
}
}Zero installazione. Serve solo Node.js per npx (che funge da bridge tra il trasporto HTTP del server remoto e lo stdio richiesto dai client MCP) e una API key SEOZoom. Funziona con Claude Desktop, Claude Code e Cursor.
Su Claude Desktop si può anche configurare dall'interfaccia grafica: vai in Impostazioni → Connettori → Aggiungi connettore personalizzato e incolla la URL del server.
Installazione locale
Per chi preferisce tenere tutto in casa. Il server gira sulla propria macchina e comunica con il client via stdio (standard input/output):
git clone https://github.com/Sozione/seozoom-mcp.git
cd seozoom-mcp
uv syncuv è un package manager Python scritto in Rust, estremamente veloce. uv sync scarica Python (se necessario) e installa tutte le dipendenze. La configurazione del client è simile, ma punta al processo locale:
{
"mcpServers": {
"seozoom": {
"command": "uv",
"args": ["--directory", "/path/to/seozoom-mcp", "run", "seozoom-mcp"],
"env": {
"SEOZOOM_API_KEY": "la-tua-api-key"
}
}
}
}Il server si avvia e si chiude automaticamente con Claude. Non c'è niente da gestire.
Sotto il cofano: architettura in 3 file
L'intero progetto è contenuto in tre file Python. Nessun framework web, nessun database, nessuna complessità superflua.
client.py — Il wrapper HTTP
La classe SEOZoomClient incapsula tutte le chiamate alle API REST di SEOZoom v2:
BASE_URL = "https://apiv2.seozoom.com/api/v2"
class SEOZoomClient:
def __init__(self) -> None:
api_key = os.environ.get("SEOZOOM_API_KEY")
if not api_key:
raise SEOZoomError("SEOZOOM_API_KEY environment variable is required")
self._api_key = api_key
self._default_db = os.environ.get("SEOZOOM_DEFAULT_DB", "it")
self._http = httpx.AsyncClient(timeout=30)Ogni metodo mappa un endpoint specifico. I valori multipli (keyword, domini, URL) vengono separati da pipe |, come richiesto dall'API SEOZoom:
async def keyword_metrics(self, keywords: list[str], db: str | None = None) -> Any:
return await self._get("keywords", {
"action": "metrics",
"db": self._db(db),
"keyword": "|".join(keywords),
})httpx è il client HTTP — asincrono di default, perfetto per i tool MCP che sono funzioni async.
server.py — I tool MCP
Il server usa FastMCP, il framework dichiarativo dell'SDK ufficiale MCP. Ogni tool è una funzione decorata con @mcp.tool():
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("seozoom")
client = SEOZoomClient()
@mcp.tool()
async def keyword_metrics(
keywords: Annotated[list[str], "Lista di keyword (max 100)"],
db: Annotated[str | None, "Database paese (it, es, fr, de, uk)"] = None,
) -> str:
"""Ottieni metriche per una o più keyword: volume di ricerca, KD, CPC, intent e trend mensili."""
return _fmt(await client.keyword_metrics(keywords, db))Tre cose rendono questo pattern potente:
Annotatedtype hints — Ogni parametro ha una descrizione testuale che l'LLM legge per capire cosa passare- Docstring — Claude usa la docstring per decidere quando invocare il tool
- Return type
str— Il JSON viene formattato con una funzione helper che aggiunge automaticamente le info sul consumo di unità API
La funzione _fmt arricchisce ogni risposta con un header informativo:
def _fmt(data: object) -> str:
if isinstance(data, dict) and "UnitsUsed" in data:
used = data.get("UnitsUsed", "?")
remaining = data.get("UnitsRemaining", "?")
rows = data.get("ResultRows", "?")
header = f"[Costo: {used} unit | Rimanenti: {remaining} | Risultati: {rows}]\n\n"
return header + json.dumps(data.get("response", data), ensure_ascii=False, indent=2)
return json.dumps(data, ensure_ascii=False, indent=2)In questo modo Claude sa sempre quante unità sono state consumate e quante ne restano — e può avvisare proattivamente se il budget si sta esaurendo.
Uso pratico: cosa puoi chiedergli
Una volta configurato, il flusso di lavoro cambia radicalmente. Ecco alcuni scenari reali.
Analisi competitiva in una domanda
"Confronta le metriche di dominio di repubblica.it e corriere.it, poi mostrami i competitor organici di entrambi"
Claude chiamerà domain_metrics e domain_competitors in sequenza, incrocerà i dati e presenterà un confronto strutturato — il tutto senza uscire dalla chat.
Audit keyword di un progetto
"Mostrami le keyword monitorate del mio progetto e evidenzia quelle che stanno perdendo posizioni"
Claude recupera la lista completa con project_keywords, filtra quelle in calo e suggerisce azioni correttive basate sui dati reali.
Content gap analysis
"Per questa URL, quali keyword hanno potenziale non sfruttato?"
Il tool url_intent_gap restituisce keyword per cui la pagina potrebbe posizionarsi ma non lo fa ancora. Claude può poi suggerire come ottimizzare il contenuto.
Monitoraggio AI Overview
"Per quali keyword il mio dominio appare nelle AI Overview di Google?"
domain_ai_keywords è un tool particolarmente interessante nel contesto attuale, dove le AI Overview stanno ridefinendo la visibilità organica.
Stack tecnico
| Componente | Tecnologia | Ruolo |
|---|---|---|
| Linguaggio | Python 3.12+ | Runtime del server |
| SDK MCP | mcp[cli] con FastMCP |
Framework dichiarativo per i tool |
| HTTP Client | httpx |
Chiamate async alle API SEOZoom |
| Package Manager | uv (Astral) |
Gestione dipendenze e virtualenv |
| Trasporto | stdio / HTTP (remoto) | Comunicazione client-server |
| Hosting remoto | Koyeb | Server Lite sempre disponibile |
| Licenza | AGPL-3.0 | Open source, copyleft forte |
Cose da sapere
Consumo API — Ogni chiamata costa tra 10 e 120 unità per riga di risultato. Il server mostra sempre il consumo nella risposta. Vale la pena tenere d'occhio il contatore, specialmente con query su domini grandi.
Database multi-paese — Di default il server usa il database italiano (it), ma supporta anche es, fr, de e uk. Basta specificarlo nella domanda: "analizza example.com sul database spagnolo".
Prima fase del progetto — Il server copre già 25 endpoint delle API SEOZoom. Ulteriori tool potranno essere aggiunti man mano che le API si espandono.
Perché l'ho reso open-source
Avrei potuto tenerlo per me — funzionava, risolveva il mio problema, fine. Ma MCP ha senso proprio quando l'ecosistema cresce. Più server esistono, più Claude (e gli altri client compatibili) diventano utili. E poi credo possa essere utile ad altre persone che, come me, lavorano con dati SEO ogni giorno e vogliono velocizzare il proprio flusso di lavoro.
Se lavori con SEOZoom e usi Claude, provalo. Se trovi bug o hai idee per nuovi tool, apri una issue. Il progetto è nella sua prima fase — c'è spazio per crescere.
Il repository è su GitHub: github.com/Sozione/seozoom-mcp