SerpApi MCP

Servidor MCP SerpApi

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

Recursos

• 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 via consultas de busca
• Dados do Mercado de Ações: Dados financeiros de empresas e dados de mercado através da integração de 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 com modos completos ou compactos
• 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 (Apps MCP): Ferramentas opcionais search_table e search_dashboard que renderizam resultados como uma interface interativa em hosts compatíveis
• Extensão para Claude Desktop: Instalação local com um clique a partir de um Pacote MCP (.mcpb), veja abaixo

Início Rápido

O Servidor MCP SerpApi 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/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

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

Extensão para Claude Desktop (Pacote MCP)

Para uma instalação local com um clique, baixe o pacote .mcpb do último lançamento (ou construa-o conforme abaixo) e abra-o com o Claude Desktop (ou arraste-o para Configurações → Extensões). O Claude Desktop solicita sua chave de API SerpApi durante a instalação, armazena-a como uma configuração sensível e executa o servidor localmente via stdio. O pacote usa o runtime MCPB uv: ele inclui apenas o código-fonte, pyproject.toml e uv.lock, e o Claude Desktop provisiona Python e as dependências bloqueadas com uv no momento da instalação, então nada é empacotado e um único pacote funciona em macOS, Windows e Linux.

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

Tudo relacionado ao pacote está em mcpb/, além de .mcpbignore na raiz do projeto. A construção regenera os esquemas dos mecanismos a partir do SerpApi Playground (--no-rebuild-engines empacota engines/ da árvore de trabalho), valida mcpb/manifest.json, empacota os arquivos rastreados pelo git menos .mcpbignore com o manifesto na raiz do pacote, então o instala em um diretório temporário e o inicia via stdio para garantir que funcione (--no-smoke pula essa última etapa). O pacote é construído apenas no momento do lançamento: enviar uma tag v<version> executa o fluxo de trabalho de lançamento, que executa a suíte de testes e então implanta o servidor hospedado, publica a entrada no Registro MCP e constrói o pacote e o anexa ao lançamento do GitHub. Pull requests executam os testes de manifesto e ponto de entrada stdio em tests/test_mcpb.py, mas não empacotam um pacote.

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

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

Dois métodos são suportados:

• Baseado em cabeçalho: Authorization: Bearer YOUR_API_KEY (recomendado: a chave permanece fora de URLs e 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 '...'

Nenhuma chave é necessária para conectar, listar ferramentas ou ler recursos. search e as ferramentas de App precisam de uma e retornam um erro sem ela.

Ferramenta de Busca

O servidor MCP tem uma ferramenta principal de Busca que suporta todos os mecanismos e tipos de resultado SerpApi. Você pode encontrar todos os parâmetros disponíveis na referência da API SerpApi. Os esquemas de parâmetros dos mecanismos também são expostos como recursos MCP: serpapi://engines (índice) e serpapi://engines/<engine>. Clientes que suportam preenchimento 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 para cada mecanismo de 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
• params.output: Formato de resposta; omita para JSON (padrão), ou defina como "md" para Markdown
• mode: Modo de resposta; "compact" remove metadados do JSON, enquanto Markdown é retornado inalterado
• ...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"}}
{"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 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.

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

search usa o catálogo de mecanismos e regras específicas de mecanismo para identificar parâmetros ausentes. Clientes que suportam MCP 2026-07-28 recebem um formulário antes de qualquer busca ser executada. 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 listando os parâmetros ausentes para que o agente possa perguntar na conversa. Veja 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. Datas e identificadores de aeroportos são verificados. Buscas baseadas em tokens, itinerários de múltiplas cidades e selected_flights_json mantêm seu comportamento existente.
• Google Hotels: destino ou consulta de hotel, data de check-in e data de check-out. O check-out deve seguir o check-in. Contagens de hóspedes e outros filtros opcionais mantêm os valores do chamador ou os padrões da API.
• Google Maps Directions: endereços de partida e destino ausentes. Coordenadas ou IDs de dados de lugares já fornecidos satisfazem o endpoint correspondente.
• Outros mecanismos do catálogo usam seus campos obrigatórios, como search_query do YouTube, find_loc do Yelp e k da Amazon. As regras de mecanismo consideram padrões e alternativas conhecidos, incluindo nós de categoria da Amazon, categorias do eBay e buscas de citações do Google Scholar.

O formulário é derivado dos argumentos originais em cada solicitação. Ele não usa requestState ou armazenamento de continuação local de processo, então uma nova tentativa pode ser executada em outra réplica sem uma chave compartilhada de proteção de estado. A autenticação é aplicada em cada solicitação HTTP, e apenas respostas para campos solicitados são usadas. Se uma resposta introduzir outro requisito, a ferramenta lista os campos restantes para o agente fornecer em uma nova chamada.

Para estender a busca guiada, adicione campos obrigatórios, descrições, tipos e opções ao arquivo engines/<engine>.json do mecanismo. Adicione uma entrada EngineInputRules em src/engine_input_rules.py quando os requisitos dependerem de outros parâmetros, padrões ou alternativas. O manipulador MCP compartilhado em src/search_input.py não precisa de ramificações específicas de mecanismo. Formulários suportam strings, números, booleanos e campos de escolha única; campos complexos não suportados recebem o erro de parâmetro ausente. Mecanismos desconhecidos passam diretamente para o SerpApi.

Interface Interativa (Apps MCP)

A ferramenta search retorna JSON por padrão. Para hosts que suportam a extensão Apps MCP (SEP-1865), duas ferramentas opcionais renderizam resultados como uma interface interativa diretamente na conversa, então o JSON SERP em massa nunca entra na janela de contexto do modelo:

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

Ambas aceitam o mesmo params que search. Hosts que não suportam Apps MCP 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

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

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 faça upgrade do seu plano SerpApi
• "Sem resultados": Tente uma consulta ou mecanismo diferente

Política de Privacidade

• Enviado: apenas os parâmetros que o host MCP passa para uma chamada de ferramenta. O servidor nunca vê o restante da conversa, ou arquivos, memória ou histórico no host.
• Encaminhado: cada busca vai para serpapi.com com sua chave de API; os resultados retornam inalterados. Veja a Política de Privacidade SerpApi para saber como o SerpApi lida com buscas e contas.
• Mantido: mcp.serpapi.com registra métricas de solicitação (método, código de status, duração) e não armazena consultas ou resultados. Uma chave no caminho da URL pode aparecer nos logs de solicitação, então prefira o cabeçalho.
• Pacote 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.

Contribuindo

1. Faça um fork do repositório
2. Crie seu branch de recurso: git checkout -b feature/amazing-feature
3. Instale as dependências: uv install
4. Faça suas alterações
5. Confirme as 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.