Serveur MCP de recherche Google pour Claude Desktop, Cursor et autres clients MCP

Que fait le serveur ?

Il expose un outil, google_search, via le Model Context Protocol. Lorsque le modèle l'appelle, le serveur envoie une requête à https://serpcrypto.com/api/v1/search, puis transforme le JSON en texte brut court : l'AI Overview si Google en a affiché un, et les meilleurs résultats avec titre, lien et snippet.

Un texte court, c'est important. Une page de résultats complète en JSON est longue, et chaque caractère renvoyé au modèle consomme du contexte. Le serveur conserve jusqu'à dix résultats et tronque l'overview à 800 caractères ; modifiez ces limites dans le code si votre client a de la place pour plus.

C'est du code à copier-coller, pas un package publié : il n'existe pas de package MCP officiel SerpCrypto à installer. Le fichier vous appartient et vous pouvez y ajouter des outils, par exemple un pour 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

Pourquoi l'outil s'appelle-t-il google_search et non web_search ?

Plusieurs clients embarquent déjà un outil nommé web_search qui utilise leur propre fournisseur. Un nom distinct évite un conflit et indique au modèle ce qu'il obtient : des résultats Google pour un pays et une langue qu'il choisit. La docstring est la description que lit le modèle ; elle précise donc les paramètres et le coût d'un appel.

Comment l'ajouter à Claude Desktop ?

Ouvrez le fichier de configuration, claude_desktop_config.json : sur macOS il se trouve dans ~/Library/Application Support/Claude/, sur Windows dans %APPDATA%\Claude\. Ajoutez le serveur sous mcpServers, avec le chemin absolu du script et votre clé dans env, puis redémarrez Claude Desktop.

Si python n'est pas dans le path que voit Claude Desktop, utilisez le chemin complet de l'interpréteur, par exemple celui de votre environnement virtuel.

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

Comment l'ajouter à Claude Code et Cursor ?

Dans Claude Code, déclarez-le depuis un terminal avec claude mcp add ; -e définit la variable d'environnement et tout ce qui suit -- est la commande à exécuter. Dans Cursor, placez le même bloc mcpServers que ci-dessus dans ~/.cursor/mcp.json pour tous les projets, ou dans .cursor/mcp.json au sein d'un projet.

Les autres clients MCP qui lancent des serveurs stdio prennent les mêmes trois éléments : une commande, ses arguments et des variables d'environnement. La page OpenClaw montre les commandes pour OpenClaw.

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

Comment sécuriser la clé API ?

Conservez-la dans le bloc env de la configuration du client ou dans votre profil shell, jamais dans serpcrypto_mcp.py. Le script peut ainsi être partagé ou commité sans la clé. Si une clé fuite, révoquez-la dans le dashboard et créez-en une nouvelle : Des clés API que vous pouvez créer et révoquer à tout moment depuis votre tableau de bord.

Donnez au serveur MCP sa propre clé. L'usage par clé indique alors combien de requêtes l'assistant effectue, séparément de vos scripts.

Combien de crédits un assistant va-t-il utiliser ?

Un par appel d'outil réussi. Une conversation où le modèle fait trois recherches coûte trois crédits. Sur le pack 25 000 recherches à 18,75 $US, cela représente des milliers de questions assistées, et Les crédits de recherche prépayés n'expirent jamais : les requêtes inutilisées restent sur votre compte jusqu'à ce que vous les utilisiez.

Pour limiter l'usage, réduisez num_results (cela ne change pas le prix, mais raccourcit les réponses) et demandez au modèle dans vos instructions de ne rechercher que lorsqu'il a besoin de faits récents.