MCP server per la ricerca Google per Claude Desktop, Cursor e altri client MCP

Cosa fa il server?

Espone un solo tool, google_search, tramite il Model Context Protocol. Quando il modello lo chiama, il server invia una richiesta a https://serpcrypto.com/api/v1/search, poi trasforma il JSON in breve testo semplice: l'AI Overview se Google ne ha mostrato uno, e i risultati principali con titolo, link e snippet.

Il testo breve conta. Una pagina di risultati completa in JSON è lunga, e ogni carattere restituito al modello consuma contesto. Il server mantiene fino a dieci risultati e taglia l'overview a 800 caratteri; modifica questi limiti nel codice se il tuo client ha spazio per di più.

Questo è codice da copiare e incollare, non un pacchetto pubblicato: non esiste un pacchetto MCP ufficiale SerpCrypto da installare. Il file è tuo e puoi aggiungere tool, per esempio uno per engine=google_news.

"""serpcrypto_mcp.py: an MCP server that gives AI clients a Google search tool.

Install once:  pip install "mcp[cli]" httpx
Run by your MCP client over stdio; the API key comes from the environment.
"""
import os

import httpx
from mcp.server.fastmcp import FastMCP

API_URL = "https://serpcrypto.com/api/v1/search"
mcp = FastMCP("serpcrypto-search")


@mcp.tool()
async def google_search(query: str, gl: str = "us", hl: str = "en", num_results: int = 5) -> str:
    """Search Google and return the top results (title, link, snippet) and the AI Overview text if any.

    gl is a two-letter country code (us, gb, de...), hl a language code (en, de, pt-BR...).
    Each call uses one SerpCrypto search credit.
    """
    headers = {"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]}
    params = {"q": query, "gl": gl, "hl": hl}
    async with httpx.AsyncClient(timeout=90) as client:
        r = await client.get(API_URL, params=params, headers=headers)
    if r.status_code != 200:
        return f"Search failed with HTTP {r.status_code}: {r.text[:300]}"
    data = r.json()
    lines = []
    overview = data.get("ai_overview") or {}
    if overview.get("text"):
        lines.append("AI Overview: " + overview["text"][:800])
    for item in data.get("organic_results", [])[: max(1, min(num_results, 10))]:
        lines.append(f"{item['position']}. {item['title']}\n{item['link']}\n{item.get('snippet', '')}")
    return "\n\n".join(lines) or "No results."


if __name__ == "__main__":
    mcp.run()  # stdio transport

Perché il tool si chiama google_search e non web_search?

Diversi client includono già un tool chiamato web_search che usa il proprio provider. Un nome distinto evita conflitti e dice al modello cosa ottiene: risultati Google per un paese e una lingua che sceglie lui. La docstring è la descrizione che legge il modello, quindi indica i parametri e il costo di una chiamata.

Come lo aggiungo a Claude Desktop?

Apri il file di configurazione, claude_desktop_config.json: su macOS si trova in ~/Library/Application Support/Claude/, su Windows in %APPDATA%\Claude\. Aggiungi il server sotto mcpServers, con il percorso assoluto dello script e la tua chiave in env, poi riavvia Claude Desktop.

Se python non è nel path che vede Claude Desktop, usa il percorso completo dell'interprete, per esempio quello dentro il tuo ambiente virtuale.

{
  "mcpServers": {
    "serpcrypto-search": {
      "command": "python",
      "args": ["/absolute/path/to/serpcrypto_mcp.py"],
      "env": {
        "SERPCRYPTO_API_KEY": "paste-your-key-here"
      }
    }
  }
}

Come lo aggiungo a Claude Code e Cursor?

In Claude Code, registralo da un terminale con claude mcp add; -e imposta la variabile d'ambiente e tutto ciò che segue -- è il comando da eseguire. In Cursor, inserisci lo stesso blocco mcpServers come sopra in ~/.cursor/mcp.json per ogni progetto, oppure in .cursor/mcp.json all'interno di un singolo progetto.

Gli altri client MCP che avviano server stdio prendono le stesse tre cose: un comando, i suoi argomenti e le variabili d'ambiente. La pagina di OpenClaw mostra i comandi per OpenClaw.

claude mcp add serpcrypto-search \
  -e SERPCRYPTO_API_KEY=paste-your-key-here \
  -- python /absolute/path/to/serpcrypto_mcp.py

Come mantengo al sicuro la chiave API?

Tienila nel blocco env della configurazione del client o nel tuo profilo shell, mai dentro serpcrypto_mcp.py. Così lo script può essere condiviso o committato senza la chiave. Se una chiave viene esposta, revocala dalla dashboard e creane una nuova: Chiavi API che puoi creare e revocare in qualsiasi momento dalla tua dashboard.

Dai al server MCP una chiave dedicata. Così il consumo per chiave mostra quante ricerche fa l'assistente, separate dai tuoi script.

Quanti crediti userà un assistente?

Uno per ogni chiamata a un tool che va a buon fine. Una chat in cui il modello cerca tre volte costa tre crediti. Sul pack da 25.000 ricerche a 18,75 USD, sono migliaia di domande assistite, e I crediti di ricerca prepagati non scadono mai: le ricerche non utilizzate restano sul tuo account finché non le usi.

Per limitare il consumo, abbassa num_results (non cambia il prezzo, ma accorcia le risposte) e indica al modello nelle tue istruzioni di cercare solo quando ha bisogno di fatti aggiornati.