SerpApi MCP Server

Serveur MCP SerpApi

Une implémentation de serveur Model Context Protocol (MCP) qui s'intègre avec 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 par 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 géolocalisée avec prévisions via des requêtes de recherche
• Données boursières : Données financières d'entreprises et de marché via l'intégration de recherche
• Traitement dynamique des résultats : Détecte et formate automatiquement différents types de résultats
• Modes de réponse flexibles : Réponses JSON complètes ou compactes
• Réponses JSON : Sortie JSON structurée avec modes complet ou compact
• Interface utilisateur interactive (applications MCP) : Outils optionnels search_table et search_dashboard qui affichent les résultats sous forme d'interface utilisateur interactive dans les hôtes compatibles

Démarrage rapide

Le serveur MCP SerpApi 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/YOUR_SERPAPI_API_KEY/mcp

Hermes

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

Codex

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

Auto-hébergement

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"
    }
  }
}

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

Authentification

Deux méthodes sont prises en charge :

• Basée sur le chemin : /YOUR_API_KEY/mcp (recommandé)
• Basée sur l'en-tête : Authorization: Bearer YOUR_API_KEY

Exemples :

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

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

Outil de recherche

Le serveur MCP dispose d'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 des moteurs sont également exposés en tant que ressources MCP : serpapi://engines (index) et serpapi://engines/<engine>.

Les paramètres que vous pouvez fournir sont spécifiques à chaque moteur 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
• mode : Mode de réponse - "complete" (par défaut) ou "compact"
• ...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"}}

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

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

Interface utilisateur interactive (applications MCP)

L'outil search par défaut renvoie du JSON et reste inchangé. Pour les hôtes qui prennent en charge l'extension MCP Apps (SEP-1865), deux outils optionnels affichent les résultats sous forme d'interface utilisateur interactive directement dans la conversation, de sorte que le JSON brut du 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, un graphique de répartition par source et un tableau de résultats avec un panneau de détails dépliable au clic.

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

Prévisualisez-les 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

# 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" : Incluez la clé dans le chemin URL /{YOUR_KEY}/mcp ou l'en-tête Bearer YOUR_KEY
• "Clé invalide" : Vérifiez sur serpapi.com/dashboard
• "Limite de débit dépassée" : Attendez ou mettez à niveau votre forfait SerpApi
• "Aucun résultat" : Essayez une requête ou un moteur différent

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 Pull Request

Licence

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