SerpApi MCP

SerpApi MCP Server

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

Recursos

• Busca em vários mecanismos: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay e mais
• Recursos dos mecanismos: esquemas de parâmetros por mecanismo disponíveis por meio de recursos MCP (consulte a ferramenta de busca)
• Dados meteorológicos em tempo real: clima baseado na localização, com previsões obtidas por consultas de busca
• Dados do mercado de ações: dados financeiros de empresas e do mercado por meio da integração com a 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 (padrão): saída JSON estruturada nos modos completo ou compacto
• Respostas em Markdown: reduza o uso de tokens em 50% em média e em mais de 90% para APIs com JSON aninhado complexo.
• Interface interativa (MCP Apps): ferramentas search_table e search_dashboard opcionais que exibem os resultados como uma interface interativa em hosts compatíveis
• Extensão do Claude Desktop: instalação local com um clique a partir de um MCP Bundle (.mcpb); veja abaixo

Início rápido

O SerpApi MCP Server está disponível como serviço hospedado em mcp.serpapi.com. Para se conectar a ele, você precisa fornecer uma chave de API. Você pode encontrar sua chave de API no painel do 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/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

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

Codex (lê a chave de SERPAPI_API_KEY no seu shell)

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

Hospedagem própria

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

Extensão do Claude Desktop (MCP bundle)

Para uma instalação local com um clique, baixe o bundle .mcpb da versão mais recente e abra-o com o Claude Desktop (ou arraste-o para Configurações → Extensões). Durante a instalação, o Claude Desktop solicita sua chave de API do SerpApi, armazena-a como uma configuração confidencial e executa o servidor localmente por stdio. O uv instala o Python e as dependências durante a instalação. O mesmo bundle funciona no macOS, Windows e Linux.

O mesmo ponto de entrada stdio funciona com qualquer host MCP local que inicie servidores como subprocessos:

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

Autenticação

Há suporte para dois métodos:

• Baseado em cabeçalho: Authorization: Bearer YOUR_API_KEY (recomendado: a chave não aparece em URLs nem em logs)
• Baseado em caminho: /YOUR_API_KEY/mcp, para clientes que não podem definir cabeçalhos

Exemplos:

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

Não é necessária uma chave para se conectar, listar ferramentas ou ler recursos. search e as ferramentas App precisam de uma chave e retornam um erro quando ela não é fornecida.

Ferramenta de busca

O servidor MCP tem uma ferramenta de busca principal que oferece suporte a todos os mecanismos e tipos de resultado do SerpApi. Você encontra todos os parâmetros disponíveis na referência da API do SerpApi. Os esquemas de parâmetros dos mecanismos também são expostos como recursos MCP: serpapi://engines (índice) e serpapi://engines/<engine>. Clientes compatíveis com conclusão de argumentos podem solicitar sugestões de nomes de mecanismos para serpapi://engines/{engine_name}. Por exemplo, o prefixo google_f sugere identificadores de mecanismos correspondentes. Isso completa o parâmetro URI do recurso, não consultas de busca arbitrárias.

Os parâmetros que você pode fornecer são específicos de cada mecanismo de API. Veja abaixo alguns exemplos de parâmetros:

• params.q (obrigatório): consulta de busca
• params.engine: mecanismo de busca (padrão: "google_light")
• params.location: filtro geográfico
• params.output: formato da resposta; omita para usar JSON (padrão) ou defina como "md" para Markdown
• mode: modo de resposta; "compact" remove os metadados do JSON, enquanto o Markdown é retornado sem alterações
• ...consulte outros parâmetros na referência da API do 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"}}
{"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"}}}

Mecanismos compatíveis: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay e outros (consulte serpapi://engines).

Tipos de resultado: caixas de resposta, resultados orgânicos, notícias, imagens, compras — detectados e formatados automaticamente.

As respostas de busca preservam a string MCP structuredContent.result existente e incluem a mesma string no conteúdo de texto. Na saída JSON, result contém o JSON serializado; os clientes existentes podem continuar analisando-o com JSON.parse(response.structuredContent.result). Na saída Markdown, ele contém o Markdown sem alterações. Erros e cancelamentos usam o mesmo wrapper. Falhas na execução da busca definem isError: true; clientes que usam o call_tool() de alto nível do FastMCP devem tratar ToolError ou usar call_tool_mcp() para inspecionar o sinalizador de resultado. Consulte resultados de ferramentas MCP.

search usa o catálogo de mecanismos e regras específicas de cada mecanismo para identificar parâmetros ausentes. Clientes compatíveis com MCP 2026-07-28 recebem um formulário antes de qualquer busca ser executada. As respostas aceitas são validadas; recusar ou cancelar não executa nenhuma busca. Clientes legados e clientes sem elicitação de formulário recebem um erro que lista os parâmetros ausentes, para que o agente possa solicitá-los na conversa. Consulte solicitações de entrada MCP.

• Google Flights: identificadores de partida e chegada, data de partida e data de retorno para viagens de ida e volta. As datas e os identificadores de aeroportos são verificados. Buscas baseadas em tokens, itinerários com várias cidades e selected_flights_json mantêm o comportamento existente.
• Google Hotels: destino ou consulta de hotel, data de check-in e data de check-out. O check-out deve ocorrer depois do check-in. A quantidade de hóspedes e outros filtros opcionais mantêm os valores fornecidos pelo chamador ou usam os padrões da API.
• Google Maps Directions: endereços de partida e destino ausentes. Coordenadas ou IDs de dados de locais já fornecidos satisfazem o endpoint correspondente.
• Outros mecanismos do catálogo usam os campos obrigatórios, como search_query do YouTube, find_loc do Yelp e k da Amazon. As regras dos mecanismos consideram padrões e alternativas conhecidos, incluindo nós de categoria da Amazon, categorias do eBay e buscas de citações do Google Scholar.

Se uma resposta introduzir outro requisito, a ferramenta lista os campos restantes para que o agente os forneça em uma nova chamada. Os formulários aceitam campos de texto, números, valores booleanos e opções de escolha única; campos complexos sem suporte geram o erro de parâmetro ausente. Mecanismos desconhecidos são encaminhados ao SerpApi.

Ferramenta de extração

A ferramenta extract lê páginas da web e retorna o conteúdo como JSON estruturado ou Markdown. Você pode extrair uma única página, descobrir os URLs de um site ou rastrear várias páginas. Encontre todos os parâmetros disponíveis na referência da API Extract ou no recurso serpapi://engines/extract.

Alguns parâmetros que você pode fornecer:

• params.url (obrigatório): URL da página ou do site
• params.mode: modo de extração; "scrape" (padrão) lê uma página, "map" descobre URLs e "crawl" extrai várias páginas
• params.include_markdown: inclui o conteúdo da página como Markdown; o padrão é true para scrape e crawl, ou defina como false para desativar
• params.output: formato da resposta; o padrão é "json" no modo completo e "md" no modo compacto. Defina-o explicitamente para substituir o formato.
• params.max_pages: número máximo de páginas a rastrear, incluindo a página inicial (padrão: 10, máximo: 100)
• params.json_restrictor: escolha quais campos retornar, como "markdown,error"
• mode: modo de resposta; "complete" (padrão) retorna a resposta completa. "compact" usa Markdown nativo por padrão. Com um params.output="json" explícito, a extração compacta de uma única página mantém o campo de nível superior markdown quando presente e preserva os erros da API. Respostas sem Markdown, incluindo resultados redirecionados para outro mecanismo, mantêm os dados com os metadados removidos. Valores explícitos de params.json_restrictor e params.include_markdown=false têm precedência ao usar JSON. Para mapas e rastreamento, o JSON compacto remove os metadados. A saída Markdown é retornada sem alterações.

Exemplos:

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

Para obter o conteúdo de uma única página como Markdown nativo, use mode="compact". Adicione params.output="json" para receber JSON contendo o campo markdown. O JSON completo inclui esse campo por padrão; o JSON de rastreamento o inclui em cada entrada pages. Definir params.output="json" e params.include_markdown=false mantém os demais campos estruturados sem Markdown.

O rastreamento consome um crédito de busca por página extraída em uma solicitação sem cache. Use params.max_pages para limitar o número de páginas extraídas.

Interface interativa (MCP apps)

A ferramenta search retorna JSON por padrão. Para hosts compatíveis com a extensão MCP Apps (SEP-1865), duas ferramentas opcionais exibem os resultados como uma interface interativa diretamente na conversa, para que o JSON SERP volumoso não entre na janela de contexto do modelo:

• search_table: resultados orgânicos em uma tabela classificável e pesquisável.
• search_dashboard: métricas resumidas, um gráfico de distribuição por fonte e uma tabela de resultados com um painel de detalhes que pode ser expandido com um clique.

Ambas aceitam o mesmo params que search. Hosts sem suporte a MCP Apps simplesmente ignoram essas ferramentas.

Solução de problemas

• "Missing API key": inclua a chave no caminho da URL /{YOUR_KEY}/mcp ou no cabeçalho Bearer YOUR_KEY
• "Invalid key": verifique em serpapi.com/dashboard
• "Rate limit exceeded": aguarde ou faça upgrade do seu plano SerpApi
• "No results": tente outra consulta ou outro mecanismo

Política de privacidade

• Enviado: somente os parâmetros que o host MCP passa para uma chamada de ferramenta. O servidor nunca vê o restante da conversa, nem arquivos, memória ou histórico no host.
• Encaminhado: cada busca é enviada a serpapi.com com sua chave de API; os resultados são retornados sem alterações. Consulte a Política de Privacidade do SerpApi para saber como o SerpApi trata buscas e contas.
• Armazenado: mcp.serpapi.com registra métricas de solicitações (método, código de status, duração) e não armazena consultas nem resultados. Uma chave no caminho da URL pode aparecer nos logs de solicitações; por isso, prefira o cabeçalho.
• Bundle local: a extensão do Claude Desktop é executada na sua máquina, mantém a chave nas configurações do Claude Desktop e chama serpapi.com diretamente. Nada passa por mcp.serpapi.com.
• Contato: privacy@serpapi.com ou abra uma issue.

Contribuição

Consulte CONTRIBUTING.md para ver as instruções de configuração do ambiente de desenvolvimento, comandos de atualização do esquema, testes, compilações do Docker e do MCP Bundle e versões.

Licença

Licença MIT — consulte o arquivo LICENSE para obter detalhes.