SERPHouse MCP

---

Sumário

• Por que usar o SERPHouse MCP
• Início Rápido (Hospedado)
• Autenticação
• O que você pode perguntar
• Visão Geral das Ferramentas
• Auto-hospedagem Local
• Auto-hospedagem com Docker
• Uso com Modelos Llama Locais (Ollama)
• Solução de Problemas
• Contribuição
• Licença

---

Por que usar o SERPHouse MCP

21 ferramentas MCP	SERP ao vivo do Google, Bing e Yahoo, verticais do Google e consultas de conta — tudo exposto com esquemas tipados
Zero código de integração	Seu assistente escolhe a ferramenta certa; você descreve o que precisa em linguagem simples
Hospedado ou auto-hospedado	Use o endpoint gerenciado em https://mcp.serphouse.com/mcp, ou execute o servidor na sua própria infraestrutura
Contexto integrado	Recursos MCP (serphouse_capabilities, serphouse_constraints, serphouse_examples) ensinam as regras de uso à IA automaticamente

---

Início Rápido (Hospedado)

O caminho mais rápido — sem etapa de build, sem servidor para manter.

1. Obtenha sua chave de API no Painel SERPHouse.

2. Adicione o servidor à configuração do seu cliente MCP usando autenticação por cabeçalho ou por URL (veja Autenticação para detalhes).

Cabeçalho (recomendado):

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Caminho da URL:

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

3. Comece a conversar. Peça ao seu assistente para pesquisar no Google, Bing ou Yahoo, consultar localizações, buscar vagas de emprego ou verificar sua conta — ele roteará para a ferramenta correta.

Instalação em um clique: Use os selos Instalar no VS Code ou Instalar no Cursor acima e substitua a chave de API de exemplo pela sua.

---

Autenticação

O servidor aceita sua chave de API do SERPHouse de duas maneiras. Use a que melhor se adequar ao seu cliente MCP.

Método	Endpoint	Como passar a chave
Cabeçalho (recomendado)	POST /mcp	Cabeçalho de requisição SERPHOUSE_API: <api_key>
Caminho da URL	POST /{apiKey}/mcp	Incorpore a chave no caminho da URL

Ferramentas e recursos podem ser descobertos sem chave. A chave de API é necessária apenas ao chamar as ferramentas da API SERPHouse.

Opção A: Cabeçalho (recomendado)

Melhor quando seu cliente MCP suporta cabeçalhos personalizados. Mantém a chave fora das URLs e dos logs de acesso do servidor.

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Exemplo auto-hospedado:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Opção B: Caminho da URL

Útil quando seu cliente suporta apenas uma URL e não pode enviar cabeçalhos personalizados.

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Exemplo auto-hospedado:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Nota: A autenticação por URL coloca a chave de API no caminho da requisição, o que pode aparecer em logs de proxy ou histórico do navegador. Prefira o método por cabeçalho quando possível.

---

O que você pode perguntar

Para equipes de SEO, agências e profissionais de marketing de SaaS que precisam de dados de busca ao vivo dentro do seu fluxo de trabalho com IA — sem painéis, scripts ou troca de contexto.

Por que usar	Exemplo de prompt
Acompanhe seus rankings	"Onde estamos ranqueados para 'software de CRM' no Google US desktop?"
Supere concorrentes	"Quem ocupa as 5 primeiras posições para 'software de gerenciamento de projetos' em Londres?"
Domine a busca local	"Principais resultados do Google Local para 'encanador de emergência' em Chicago."
Descubra palavras-chave	"O que o Autocomplete sugere para 'melhor saas para'?"
Monitore posições	"Execute uma verificação de SERP no Bing mobile para nossa marca em NYC e relate nosso ranking."
Cobertura multi-mecanismo	"Compare os resultados de notícias do Yahoo e do Google para 'veículos elétricos'."

---

Visão Geral das Ferramentas

O servidor expõe 21 ferramentas em cinco categorias. Requisições de SERP do Google e Bing exigem exatamente um campo de localização — loc (ex.: Austin,Texas,United States) ou loc_id (de serphouse_location_search). Nunca envie ambos ou omita ambos nesses endpoints. As ferramentas de SERP do Yahoo não exigem localização.

Referência

Ferramenta	Descrição
serphouse_domain_list	Domínios de busca suportados do Google, Bing e Yahoo
serphouse_language_list	Códigos de idioma por tipo de mecanismo de busca
serphouse_location_search	Resolve nomes de cidade/país para loc_id
serphouse_account_info	Saldo da conta e uso

Google SERP

Ferramenta	Descrição
serphouse_google_web	Busca web no Google
serphouse_google_image	Busca de imagens no Google
serphouse_google_news	Busca de notícias no Google
serphouse_google_shop	Busca de compras no Google
serphouse_serp_google_advanced	SERP avançada do Google com parâmetros estendidos (até 100 resultados)

Bing SERP

Ferramenta	Descrição
serphouse_bing_web	Busca web no Bing
serphouse_bing_image	Busca de imagens no Bing
serphouse_bing_news	Busca de notícias no Bing

Yahoo SERP

Ferramenta	Descrição
serphouse_yahoo_web	Busca web no Yahoo
serphouse_yahoo_image	Busca de imagens no Yahoo
serphouse_yahoo_news	Busca de notícias no Yahoo

Verticais do Google

Ferramenta	Descrição
serphouse_google_jobs	Busca de empregos no Google
serphouse_google_autocomplete	Sugestões do Google Autocomplete
serphouse_google_videos	Resultados de vídeos do Google
serphouse_google_short_videos	Vídeos curtos do Google (Shorts)
serphouse_google_forums	Resultados de fóruns do Google
serphouse_google_local	Resultados do Google Local / Maps

---

Auto-hospedagem Local

Execute o servidor na sua máquina para controle total ou desenvolvimento local.

git clone https://github.com/SERPHouse/serphouse-mcp.git
cd serphouse-mcp
npm install
npm run build
npm start

O servidor escuta em http://localhost:3000. Endpoints MCP:

• POST /mcp — passe a chave de API via cabeçalho SERPHOUSE_API
• POST /{apiKey}/mcp — passe a chave de API no caminho da URL

Aponte seu cliente MCP para a instância local (veja Autenticação para ambas as opções):

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Ou com autenticação por URL:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Comandos

Comando	Descrição
npm run build	Compila TypeScript para dist/
npm start	Executa o servidor HTTP (http://localhost:3000/mcp)
npm run start:stdio	Executa o servidor de transporte stdio (modo de processo MCP local)
npm run dev	Executa o servidor HTTP com recarga automática
npm run dev:ins	Inicia o MCP Inspector contra o servidor stdio para depuração
npm run typecheck	Verifica tipos sem emitir arquivos

Verificação de saúde: GET http://localhost:3000/health

Opções do Servidor

Variável	Padrão	Descrição
PORT	3000	Porta de escuta HTTP
HOST	0.0.0.0	Endereço de bind HTTP

A autenticação suporta tanto cabeçalho quanto caminho de URL. Veja Autenticação.

---

Auto-hospedagem com Docker

Execute o servidor MCP localmente no Docker sem instalar Node.js.

docker compose up -d

O servidor roda em http://localhost:3000/mcp (autenticação por cabeçalho) ou http://localhost:3000/{apiKey}/mcp (autenticação por URL).

Conecte seu cliente MCP usando qualquer um dos métodos de Autenticação:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Ou:

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

---

Uso com Modelos Llama Locais (Ollama)

Conecte seu Servidor SERPHouse MCP a um modelo Llama local (ex.: Llama 3.1 ou 3.2) usando ollmcp — um cliente de interface de terminal interativa que traz o poder da busca em tempo real diretamente para seu fluxo de trabalho com LLM local.

Pré-requisitos

Requisito	Notas
Modelo Llama com chamada de ferramentas	Um modelo que suporte chamadas de ferramentas (ex.: llama3.1, llama3.2) instalado e rodando via Ollama
Python 3.10+	Necessário para executar o cliente de terminal ollmcp
Node.js	Necessário para executar o servidor MCP SERPHouse via npx

1. Instale o ollmcp

ollmcp é um cliente Python, então instale-o globalmente com pip:

pip install --upgrade ollmcp

2. Crie um arquivo config.json

O cliente precisa de um perfil de configuração que informe como conectar ao servidor SERPHouse e passar suas credenciais de API. Crie um config.json na sua pasta de trabalho usando qualquer método de autenticação de Autenticação:

{
  "mcpServers": {
    "serphouse-mcp": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

Ou com autenticação por URL:

{
  "mcpServers": {
    "serphouse-mcp": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

Substitua YOUR_SERPHouse_API_KEY pela sua chave ativa do Painel SERPHouse.

3. Execute o cliente de terminal

Inicie a interface interativa, passando seu perfil de configuração e o modelo alvo:

ollmcp --servers-json config.json --model llama3.1

Quando a interface de terminal carregar:

1. Selecione seu modelo Llama alvo na lista de modelos.
2. Envie um prompt que precise de dados web ao vivo — ex.: "Consulte os principais resultados do Google para 'melhores ferramentas para desenvolvedores' usando SERPHouse."
3. Observe seu modelo Llama local chamar as ferramentas SERPHouse e transformar dados de SERP em tempo real em uma resposta conversacional.

Modelos Compatíveis

Os seguintes modelos Ollama funcionam bem com uso de ferramentas:

• gemma4
• qwen3.5
• lfm2.5-thinking
• llama3.2
• mistral

Para uma lista completa de modelos Ollama com capacidade de uso de ferramentas, visite a página oficial de modelos Ollama.

Para modelos que também podem processar imagens retornadas pelas ferramentas, veja a página de modelos de visão do Ollama.

---

Solução de Problemas

Problema	Correção
Chave de API ausente	Envie o cabeçalho SERPHOUSE_API em POST /mcp, ou use POST /{apiKey}/mcp com a chave no caminho da URL
Chave inválida	Verifique sua chave no painel SERPHouse
Crédito esgotado	Verifique o saldo com serphouse_account_info
Erro de localização	Para ferramentas do Google e Bing, inclua loc ou loc_id (não ambos); use serphouse_location_search para resolver IDs. As ferramentas de SERP do Yahoo não exigem localização.
Conexão recusada	Confirme que o servidor está rodando e que a URL/porta está correta

---

Contribuição

Contribuições são bem-vindas. Por favor, mantenha as mudanças focadas e alinhadas ao estilo de código existente.

git checkout -b feature/your-feature
npm install
# make changes
npm run typecheck
git commit -m "Add your feature"
git push origin feature/your-feature

Em seguida, abra um Pull Request. Atualize este README se você alterar a configuração ou a instalação.

---

Licença

Licença MIT — Copyright SERPHouse.