SerpApi MCP

Serveur MCP SerpApi

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

Fonctionnalités

• Recherche multi-moteurs : Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay et plus
• Ressources moteur : Schémas de paramètres par moteur disponibles via les ressources MCP (voir l'outil de recherche)
• Données météo en temps réel : Météo basée sur la localisation avec prévisions via les requêtes de recherche
• Données boursières : Données financières des entreprises et données de marché via l'intégration de recherche
• Traitement dynamique des résultats : Détecte et formate automatiquement les 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 avec modes complet ou compact
• Réponses Markdown : Réduit l'utilisation de tokens de 50 % en moyenne et de plus de 90 % pour les API avec JSON imbriqué complexe.
• Interface utilisateur interactive (applications MCP) : Outils search_table et search_dashboard facultatifs qui affichent les résultats sous forme d'interface utilisateur interactive dans les hôtes compatibles
• Extension Claude Desktop : Installation locale en un clic depuis un bundle MCP (.mcpb), voir ci-dessous

Démarrage rapide

Le serveur SerpApi MCP est disponible en tant que service hébergé sur mcp.serpapi.com. Pour vous y connecter, vous devez fournir une clé API. Vous pouvez trouver 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 (lit 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

Auto-hébergement

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

Configurez Claude Desktop :

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

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

Extension Claude Desktop (bundle MCP)

Pour une installation locale en un clic, téléchargez le bundle .mcpb depuis la dernière version (ou construisez-le comme ci-dessous) et ouvrez-le avec Claude Desktop (ou déposez-le sur Paramètres → Extensions). Claude Desktop demande votre clé API SerpApi lors de l'installation, la stocke comme paramètre sensible et exécute le serveur localement via stdio. Le bundle utilise le runtime MCPB uv : il fournit uniquement le code source, pyproject.toml et uv.lock, et Claude Desktop provisionne Python et les dépendances verrouillées avec uv lors de l'installation, donc rien n'est intégré et un seul bundle fonctionne sur macOS, Windows et Linux.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Tout ce qui concerne le bundle se trouve dans mcpb/, plus .mcpbignore à la racine du projet. La construction régénère les schémas moteur depuis le SerpApi Playground (--no-rebuild-engines regroupe engines/ depuis l'arborescence de travail à la place), valide mcpb/manifest.json, empaquette les fichiers suivis par git moins .mcpbignore avec le manifeste à la racine du bundle, puis l'installe dans un répertoire temporaire et le démarre via stdio pour s'assurer qu'il fonctionne (--no-smoke saute cette dernière étape). Le bundle n'est construit qu'au moment de la version : pousser une balise v<version> exécute le workflow de version, qui exécute la suite de tests puis déploie le serveur hébergé, publie l'entrée du registre MCP et construit le bundle et le joint à la version GitHub. Les demandes d'extraction exécutent les tests du manifeste et du point d'entrée stdio dans tests/test_mcpb.py mais n'empaquettent pas de bundle.

Le même point d'entrée stdio fonctionne avec tout hôte MCP local qui lance des 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 :

• Basée sur l'en-tête : Authorization: Bearer YOUR_API_KEY (recommandé : la clé reste hors des URL et des journaux)
• Basée sur le 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 sans elle.

Outil de recherche

Le serveur MCP possède un outil de recherche principal qui prend en charge tous les moteurs et types de résultats SerpApi. Vous pouvez trouver tous les paramètres disponibles dans la référence API SerpApi. Les schémas de paramètres moteur 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 d'arguments peuvent demander des suggestions de noms de moteurs pour serpapi://engines/{engine_name}. Par exemple, le préfixe google_f suggère des identifiants de moteurs correspondants. Cela complète le paramètre URI de la ressource, pas les requêtes de recherche arbitraires.

Les paramètres que vous pouvez fournir sont spécifiques à chaque moteur API. Quelques exemples de paramètres sont fournis ci-dessous :

• 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 ; omettre pour JSON (par défaut), ou définir sur "md" pour Markdown
• mode : Mode de réponse ; "compact" supprime les métadonnées du JSON, tandis que le Markdown est renvoyé inchangé
• ...voir les autres paramètres dans la référence 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 plus (voir serpapi://engines).

Types de résultats : Boîtes de réponse, résultats organiques, actualités, images, shopping - détectés et formatés automatiquement.

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

search utilise le catalogue de moteurs et les règles spécifiques aux moteurs pour identifier les paramètres manquants. Les clients prenant en charge MCP 2026-07-28 reçoivent un formulaire avant toute exécution de recherche. Les réponses acceptées sont validées ; le refus ou l'annulation n'exécute aucune recherche. Les clients hérités et les clients sans élicitation de formulaire reçoivent une erreur listant les paramètres manquants afin que l'agent puisse demander dans la conversation. Voir demandes d'entrée 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 identifiants d'aéroport sont vérifiés. Les recherches basées sur des jetons, les itinéraires multi-villes et selected_flights_json conservent leur comportement existant.
• Google Hotels : destination ou requête d'hôtel, date d'arrivée et date de départ. Le départ doit suivre l'arrivée. Les nombres d'invités et autres filtres facultatifs conservent les valeurs de 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 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 de YouTube, find_loc de Yelp et k d'Amazon. Les règles moteur tiennent compte des valeurs par défaut et alternatives connues, y compris les nœuds de catégorie Amazon, les catégories eBay et les recherches de citations Google Scholar.

Le formulaire est dérivé des arguments d'origine à chaque requête. Il n'utilise pas de requestState ni de stockage de continuation local au processus, donc une nouvelle tentative peut s'exécuter sur une autre réplique sans clé de protection d'état partagée. L'authentification est appliquée sur chaque requête HTTP, et seules les réponses pour les champs demandés sont utilisées. Si une réponse introduit une autre exigence, l'outil liste les champs restants pour que l'agent les fournisse dans un nouvel appel.

Pour étendre la recherche guidée, ajoutez des champs obligatoires, descriptions, types et options au fichier engines/<engine>.json du moteur. Ajoutez une entrée EngineInputRules dans src/engine_input_rules.py lorsque les exigences dépendent d'autres paramètres, valeurs par défaut ou alternatives. Le gestionnaire MCP partagé dans src/search_input.py n'a pas besoin de branches spécifiques au moteur. Les formulaires prennent en charge les chaînes, nombres, booléens et champs à choix unique ; les champs complexes non pris en charge reçoivent l'erreur de paramètre manquant. Les moteurs inconnus sont transmis à SerpApi.

Interface utilisateur interactive (applications MCP)

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 facultatifs affichent les résultats sous forme d'interface utilisateur interactive directement dans la conversation, de sorte que le gros JSON SERP 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 : métriques récapitulatives, graphique de répartition des sources et tableau de résultats avec panneau de détail cliquable pour développer.

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

Aperçu localement sans hôte MCP :

uv run fastmcp dev apps src/server.py

Développement

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Dépannage

• "Clé API manquante" : Inclure la clé dans le chemin URL /{YOUR_KEY}/mcp ou l'en-tête Bearer YOUR_KEY
• "Clé invalide" : Vérifier sur serpapi.com/dashboard
• "Limite de débit dépassée" : Attendre ou mettre à niveau votre plan SerpApi
• "Aucun résultat" : Essayer une autre requête ou un autre moteur

Politique de confidentialité

• Envoyé : uniquement les paramètres que l'hôte MCP transmet à un appel d'outil. Le serveur ne voit jamais le reste de la conversation, ni les fichiers, la mémoire ou l'historique sur l'hôte.
• Transféré : chaque recherche va à serpapi.com avec votre clé API ; les résultats reviennent inchangés. Voir la politique de confidentialité SerpApi pour savoir comment SerpApi gère les recherches et les comptes.
• Conservé : mcp.serpapi.com enregistre les métriques de requête (méthode, code de statut, durée) et ne stocke aucune requête ni résultat. Une clé dans le chemin URL peut apparaître dans les journaux de requêtes, donc préférez 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 serpapi.com directement. Rien ne passe par mcp.serpapi.com.
• Contact : privacy@serpapi.com, ou ouvrez un problème.

Contribution

1. Forkez le dépôt
2. Créez votre branche de fonctionnalité : git checkout -b feature/amazing-feature
3. Installez les dépendances : uv install
4. Apportez vos modifications
5. Validez les modifications : git commit -m 'Add amazing feature'
6. Poussez vers la branche : git push origin feature/amazing-feature
7. Ouvrez une demande d'extraction

Licence

Licence MIT - voir le fichier LICENSE pour plus de détails.