SerpApi MCP

Servidor SerpApi MCP

Uma implementação de servidor Model Context Protocol (MCP) que se integra com SerpApi para resultados abrangentes de mecanismos de busca e extração de dados.

Funcionalidades

• Busca Multi-Mecanismo: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay e mais
• Recursos de Mecanismo: Esquemas de parâmetros por mecanismo disponíveis via recursos MCP (veja Ferramenta de Busca)
• Dados Meteorológicos em Tempo Real: Clima baseado em localização com previsões através de consultas de busca
• Dados do Mercado de Ações: Finanças de empresas e dados de mercado através da integração com busca
• Processamento Dinâmico de Resultados: Detecta e formata automaticamente diferentes tipos de resultados
• Modos de Resposta Flexíveis: Respostas JSON completas ou compactas
• Respostas JSON: Saída JSON estruturada com modos completo ou compacto
• IU Interativa (MCP Apps): Ferramentas opcionais search_table e search_dashboard que renderizam resultados como uma IU interativa em hosts compatíveis

Início Rápido

O Servidor SerpApi MCP está disponível como um serviço hospedado em mcp.serpapi.com. Para conectar-se a ele, você precisa fornecer uma chave de API. Você pode encontrar sua chave de API no seu painel SerpApi.

Você pode configurar o Claude Desktop para usar o servidor hospedado:

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

Você também pode adicionar o servidor hospedado a estes clientes 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-Hospedagem

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

Configure o Claude Desktop:

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

Obtenha sua chave de API: serpapi.com/manage-api-key

Autenticação

Dois métodos são suportados:

• Baseado em Caminho: /YOUR_API_KEY/mcp (recomendado)
• Baseado em Cabeçalho: Authorization: Bearer YOUR_API_KEY

Exemplos:

# 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 '...'

Ferramenta de Busca

O servidor MCP possui uma Ferramenta de Busca principal que suporta todos os mecanismos e tipos de resultado do SerpApi. Você pode encontrar todos os parâmetros disponíveis na referência da API SerpApi. Os esquemas de parâmetros do mecanismo também são expostos como recursos MCP: serpapi://engines (índice) e serpapi://engines/<engine>.

Os parâmetros que você pode fornecer são específicos para cada mecanismo da API. Alguns parâmetros de exemplo são fornecidos abaixo:

• params.q (obrigatório): Consulta de busca
• params.engine: Mecanismo de busca (padrão: "google_light")
• params.location: Filtro geográfico
• mode: Modo de resposta - "complete" (padrão) ou "compact"
• ...veja outros parâmetros na referência da API SerpApi

Exemplos:

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

Mecanismos Suportados: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay e mais (veja serpapi://engines).

Tipos de Resultado: Caixas de resposta, resultados orgânicos, notícias, imagens, compras - detectados e formatados automaticamente.

IU Interativa (MCP Apps)

A ferramenta padrão search retorna JSON e permanece inalterada. Para hosts que suportam a extensão MCP Apps (SEP-1865), duas ferramentas opcionais renderizam resultados como uma IU interativa diretamente na conversa, para que o JSON SERP volumoso nunca entre na janela de contexto do modelo:

• search_table: resultados orgânicos como uma tabela ordenável e pesquisável.
• search_dashboard: métricas de resumo, um gráfico de distribuição por fonte e uma tabela de resultados com um painel de detalhes expansível ao clicar.

Ambas aceitam os mesmos params que search. Hosts que não suportam MCP Apps simplesmente ignoram essas ferramentas.

Visualize-as localmente sem um host MCP:

uv run fastmcp dev apps src/server.py

Desenvolvimento

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

Solução de Problemas

• "Chave de API ausente": Inclua a chave no caminho da URL /{YOUR_KEY}/mcp ou no cabeçalho Bearer YOUR_KEY
• "Chave inválida": Verifique em serpapi.com/dashboard
• "Limite de taxa excedido": Aguarde ou atualize seu plano SerpApi
• "Sem resultados": Tente uma consulta ou mecanismo diferente

Contribuindo

1. Faça um fork do repositório
2. Crie seu branch de funcionalidade: git checkout -b feature/amazing-feature
3. Instale as dependências: uv install
4. Faça suas alterações
5. Faça commit das alterações: git commit -m 'Add amazing feature'
6. Envie para o branch: git push origin feature/amazing-feature
7. Abra um Pull Request

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.