SerpApi MCP

SerpApi MCP Server

Une implémentation de serveur Model Context Protocol (MCP) qui s’intègre à SerpApi pour fournir des résultats complets de moteurs de recherche et extraire des données.

Fonctionnalités

• Recherche multi-moteurs : Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay et bien d’autres
• Ressources des moteurs : schémas de paramètres propres à chaque moteur disponibles via les ressources MCP (voir l’outil Search)
• Données météo en temps réel : météo et prévisions selon la localisation, obtenues via des requêtes de recherche
• Données boursières : données financières et de marché des entreprises grâce à l’intégration de la recherche
• Traitement dynamique des résultats : détection et mise en forme automatiques des différents types de résultats
• Modes de réponse flexibles : réponses JSON complètes ou compactes
• Réponses JSON (par défaut) : sortie JSON structurée, en mode complet ou compact
• Réponses Markdown : réduisez l’utilisation de jetons de 50 % en moyenne et de plus de 90 % pour les API avec des objets JSON imbriqués complexes.
• Interface interactive (MCP Apps) : outils search_table et search_dashboard activés sur demande, qui affichent les résultats sous forme d’interface interactive dans les hôtes compatibles
• Extension Claude Desktop : installation locale en un clic depuis un MCP Bundle (.mcpb), voir ci-dessous

Démarrage rapide

SerpApi MCP Server est disponible en tant que service hébergé sur mcp.serpapi.com. Pour vous y connecter, vous devez fournir une clé API. Vous trouverez votre clé API sur votre tableau de bord SerpApi.

Vous pouvez configurer Claude Desktop pour utiliser le serveur hébergé :

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Vous pouvez également ajouter le serveur hébergé à ces clients MCP :

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex (récupère la clé depuis SERPAPI_API_KEY dans votre shell)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

Hébergement autonome

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Configurer Claude Desktop :

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Obtenir votre clé API : serpapi.com/manage-api-key

Extension Claude Desktop (MCP bundle)

Pour une installation locale en un clic, téléchargez le bundle .mcpb depuis la dernière version et ouvrez-le avec Claude Desktop (ou déposez-le dans Settings → Extensions). Claude Desktop vous demande votre clé API SerpApi pendant l’installation, l’enregistre comme paramètre sensible et exécute le serveur localement via stdio. Il installe Python et les dépendances avec uv au moment de l’installation. Le même bundle fonctionne sur macOS, Windows et Linux.

Le même point d’entrée stdio fonctionne avec tout hôte MCP local qui lance les serveurs en tant que sous-processus :

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

Authentification

Deux méthodes sont prises en charge :

• Par en-tête : Authorization: Bearer YOUR_API_KEY (recommandé : la clé n’apparaît ni dans les URL ni dans les journaux)
• Par chemin : /YOUR_API_KEY/mcp, pour les clients qui ne peuvent pas définir d’en-têtes

Exemples :

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

Aucune clé n’est nécessaire pour se connecter, lister les outils ou lire les ressources. search et les outils App en nécessitent une et renvoient une erreur en son absence.

Outil Search

Le serveur MCP dispose d’un outil de recherche principal qui prend en charge tous les moteurs et types de résultats SerpApi. Vous trouverez tous les paramètres disponibles dans la référence de l’API SerpApi. Les schémas de paramètres des moteurs sont également exposés en tant que ressources MCP : serpapi://engines (index) et serpapi://engines/<engine>. Les clients qui prennent en charge la complétion des arguments peuvent demander des suggestions de noms de moteurs pour serpapi://engines/{engine_name}. Par exemple, le préfixe google_f suggère les identifiants de moteur correspondants. Cette complétion concerne le paramètre d’URI de la ressource, et non les requêtes de recherche arbitraires.

Les paramètres que vous pouvez fournir dépendent de chaque moteur d’API. Voici quelques exemples de paramètres :

• params.q (obligatoire) : requête de recherche
• params.engine : moteur de recherche (par défaut : "google_light")
• params.location : filtre géographique
• params.output : format de réponse ; omettez-le pour obtenir du JSON (par défaut), ou définissez-le sur "md" pour obtenir du Markdown
• mode : mode de réponse ; "compact" supprime les métadonnées du JSON, tandis que le Markdown est renvoyé sans modification
• ...voir les autres paramètres dans la référence de l’API SerpApi

Exemples :

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

Moteurs pris en charge : Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay et bien d’autres (voir serpapi://engines).

Types de résultats : encadrés de réponse, résultats organiques, actualités, images, achats — détectés et mis en forme automatiquement.

Les réponses de recherche conservent la chaîne MCP structuredContent.result existante et incluent cette même chaîne dans le contenu textuel. Pour une sortie JSON, result contient le JSON sérialisé ; les clients existants peuvent continuer à l’analyser avec JSON.parse(response.structuredContent.result). Pour une sortie Markdown, il contient le Markdown inchangé. Les erreurs et les annulations utilisent le même wrapper. Les échecs d’exécution de la recherche définissent isError: true ; les clients qui utilisent le call_tool() de haut niveau de FastMCP doivent gérer ToolError, ou utiliser call_tool_mcp() pour examiner l’indicateur de résultat. Voir Résultats des outils MCP.

search utilise le catalogue des moteurs et les règles propres à chaque moteur pour identifier les paramètres manquants. Les clients compatibles avec MCP 2026-07-28 reçoivent un formulaire avant le lancement de toute recherche. Les réponses acceptées sont validées ; un refus ou une annulation ne lance aucune recherche. Les clients hérités et ceux qui ne prennent pas en charge la sollicitation de formulaire reçoivent une erreur indiquant les paramètres manquants, afin que l’agent puisse les demander dans la conversation. Voir Demandes de saisie MCP.

• Google Flights : identifiants de départ et d’arrivée, date de départ et date de retour pour les allers-retours. Les dates et les identifiants d’aéroport sont vérifiés. Les recherches par jeton, les itinéraires multi-destinations et selected_flights_json conservent leur comportement actuel.
• Google Hotels : destination ou requête d’hôtel, date d’arrivée et date de départ. La date de départ doit être postérieure à la date d’arrivée. Les nombres de voyageurs et les autres filtres facultatifs conservent les valeurs fournies par l’appelant ou les valeurs par défaut de l’API.
• Google Maps Directions : adresses de départ et de destination manquantes. Les coordonnées ou les identifiants de données de lieu déjà fournis satisfont le point de terminaison correspondant.
• Les autres moteurs du catalogue utilisent leurs champs obligatoires, comme search_query pour YouTube, find_loc pour Yelp et k pour Amazon. Les règles des moteurs tiennent compte des valeurs par défaut et des alternatives connues, notamment les nœuds de catégorie Amazon, les catégories eBay et les recherches de citations Google Scholar.

Si une réponse introduit une autre exigence, l’outil indique les champs restants que l’agent doit fournir dans un nouvel appel. Les formulaires prennent en charge les chaînes, les nombres, les booléens et les champs à choix unique ; les champs complexes non pris en charge génèrent une erreur de paramètre manquant. Les moteurs inconnus sont transmis à SerpApi.

Outil Extract

L’outil extract lit des pages Web et renvoie leur contenu sous forme de JSON structuré ou de Markdown. Vous pouvez extraire une seule page, découvrir les URL d’un site Web ou explorer plusieurs pages. Retrouvez tous les paramètres disponibles dans la référence de l’API Extract ou dans la ressource serpapi://engines/extract.

Voici quelques paramètres que vous pouvez fournir :

• params.url (obligatoire) : URL de la page ou du site Web
• params.mode : mode d’extraction ; "scrape" (par défaut) lit une page, "map" découvre des URL et "crawl" extrait plusieurs pages
• params.include_markdown : inclure le contenu de la page au format Markdown ; par défaut, la valeur est true pour le scraping et l’exploration, ou définissez-la sur false pour désactiver cette option
• params.output : format de réponse ; par défaut, la valeur est "json" en mode complet et "md" en mode compact. Définissez-le explicitement pour remplacer le format.
• params.max_pages : nombre maximal de pages à explorer, page de départ comprise (par défaut : 10, maximum : 100)
• params.json_restrictor : choisir les champs à renvoyer, par exemple "markdown,error"
• mode : mode de réponse ; "complete" (par défaut) renvoie la réponse complète. "compact" utilise par défaut le Markdown natif. Avec un params.output="json" explicite, l’extraction compacte d’une seule page conserve le champ de premier niveau markdown lorsqu’il est présent et conserve les erreurs de l’API. Les réponses sans Markdown, y compris les résultats redirigés vers un autre moteur, conservent leurs données sans les métadonnées. Les valeurs explicites de params.json_restrictor et params.include_markdown=false sont prioritaires lors de l’utilisation du JSON. Pour les modes map et crawl, le JSON compact supprime les métadonnées. La sortie Markdown est renvoyée sans modification.

Exemples :

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

Pour obtenir le contenu d’une seule page en Markdown natif, utilisez mode="compact". Ajoutez params.output="json" pour recevoir du JSON contenant le champ markdown. Le JSON complet inclut ce champ par défaut ; le JSON d’exploration l’inclut dans chaque entrée pages. Définir params.output="json" et params.include_markdown=false permet de conserver les autres champs structurés sans Markdown.

L’exploration consomme un crédit de recherche par page extraite avec succès lors d’une requête non mise en cache. Utilisez params.max_pages pour limiter le nombre de pages extraites.

Interface interactive (MCP apps)

L’outil search renvoie du JSON par défaut. Pour les hôtes qui prennent en charge l’extension MCP Apps (SEP-1865), deux outils activés sur demande affichent les résultats sous forme d’interface interactive directement dans la conversation, de sorte que le JSON SERP volumineux n’entre jamais dans la fenêtre de contexte du modèle :

• search_table : résultats organiques sous forme de tableau triable et consultable.
• search_dashboard : indicateurs récapitulatifs, graphique de répartition des sources et tableau de résultats avec panneau de détails extensible au clic.

Les deux acceptent le même params que search. Les hôtes qui ne prennent pas en charge MCP Apps ignorent simplement ces outils.

Dépannage

• « Clé API manquante » : incluez la clé dans le chemin de l’URL /{YOUR_KEY}/mcp ou dans l’en-tête Bearer YOUR_KEY
• « Clé invalide » : vérifiez-la sur serpapi.com/dashboard
• « Limite de requêtes dépassée » : patientez ou passez à une offre SerpApi supérieure
• « Aucun résultat » : essayez une autre requête ou un autre moteur

Politique de confidentialité

• Envoyé : seuls les paramètres transmis à un appel d’outil par l’hôte MCP. Le serveur ne voit jamais le reste de la conversation, ni les fichiers, la mémoire ou l’historique de l’hôte.
• Transmis : chaque recherche est envoyée à serpapi.com avec votre clé API ; les résultats sont renvoyés sans modification. Consultez la Politique de confidentialité de SerpApi pour savoir comment SerpApi traite les recherches et les comptes.
• Conservé : mcp.serpapi.com enregistre les métriques des requêtes (méthode, code d’état, durée) et ne stocke ni requêtes ni résultats. Une clé dans le chemin de l’URL peut apparaître dans les journaux de requêtes ; privilégiez donc l’en-tête.
• Bundle local : l’extension Claude Desktop s’exécute sur votre machine, conserve la clé dans les paramètres de Claude Desktop et appelle directement serpapi.com. Rien ne transite par mcp.serpapi.com.
• Contact : privacy@serpapi.com, ou ouvrez un ticket.

Contribution

Consultez CONTRIBUTING.md pour les instructions de configuration du développement, les commandes d’actualisation des schémas, les tests, la création de Docker et de MCP Bundle, ainsi que les versions.

Licence

Licence MIT — consultez le fichier LICENSE pour plus de détails.