mcp-google-merchants

Google Merchant Center MCP

Inglês | Русский

A1 Google Merchant Center MCP conecta um aplicativo de IA à sua conta do Google Merchant Center. Descubra por que os produtos foram reprovados, inspecione feeds e promoções, explore relatórios e preços de mercado e faça alterações deliberadas nos dados do produto quando necessário.

Ele funciona com os dados do Merchant Center por trás dos anúncios do Shopping: produtos, fontes de dados, promoções e relatórios. Campanhas, orçamentos e lances pertencem ao Google Ads e estão fora deste servidor.

• 22 ferramentas. 15 operações apenas leem dados do Merchant Center; 5 gravam dados de produto, fonte de dados ou promoção; 2 são potencialmente destrutivas.
• Seu acesso ao Google. O servidor usa suas credenciais OAuth e a Merchant API v1 — ele não cria uma conta separada no Merchant Center.
• Alterações cientes da fonte. As entradas de produto e promoção só podem ser alteradas por meio de uma fonte de dados de API. Um feed de arquivo pode ser buscado novamente, mas seu conteúdo não é editado aqui.
• Limites visíveis. As ferramentas carregam metadados somente leitura, gravação ou destrutivos, para que um cliente de IA possa distinguir uma inspeção de uma alteração ao vivo.

Comece com uma pergunta somente leitura:

Quais produtos estão reprovados e quais problemas o Google relata para cada um?

Conecte o servidor · Explore casos de uso · Abra a documentação técnica

Veja funcionando em um minuto

Você: Quais produtos estão reprovados e quais problemas o Google relata para cada um?

Assistente: Lista os produtos afetados e explica os problemas no nível do item que o Merchant Center relata.

Você: Mostre o preço e a disponibilidade atuais do produto SKU-123 e prepare uma atualização de disponibilidade para in_stock.

Assistente: Mostra a entrada de produto atual, a fonte de dados de API à qual ela pertence e a alteração exata a ser feita. Ele pede confirmação antes de atualizar a entrada de produto ao vivo.

Você: Confirme a atualização.

Assistente: Envia a atualização e explica que o Merchant Center processa os dados do produto de forma assíncrona. O produto processado e seu status de qualidade podem levar vários minutos para atualizar.

Conteúdo

• Início rápido
• O que você pode pedir para ele fazer
• Como os dados do Merchant Center são conectados
• O que pode mudar
• Obtendo acesso
• Configuração
• Dados e telemetria
• Limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa do Node.js 20+, de uma conta do Google Merchant Center e de um projeto do Google Cloud registrado no Merchant Center. As credenciais OAuth não são necessárias no momento da instalação — o servidor conecta-se a partir da conversa; consulte Obtendo acesso.

1. Adicione o servidor ao seu aplicativo de IA usando uma das instruções abaixo.
2. Diga "conectar Google Merchant Center": o assistente orienta você pelo cliente OAuth e pelo consentimento do navegador, sem arquivos de configuração e sem reinicialização.
3. Faça a primeira pergunta somente leitura acima.

codex mcp add google-merchants \
  -- npx -y mcp-google-merchants@latest

codex mcp list

claude mcp add \
  --transport stdio \
  --scope user \
  google-merchants \
  -- npx -y mcp-google-merchants@latest

claude mcp list

{
  "mcpServers": {
    "google-merchants": {
      "command": "npx",
      "args": ["-y", "mcp-google-merchants@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-merchants@latest"]
    }
  }
}

{
  "servers": {
    "google-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-merchants@latest"]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "google_merchants_client_id",
      "description": "Google OAuth client ID"
    },
    {
      "type": "promptString",
      "id": "google_merchants_client_secret",
      "description": "Google OAuth client secret",
      "password": true
    },
    {
      "type": "promptString",
      "id": "google_merchants_refresh_token",
      "description": "Google OAuth refresh token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "google_merchants_account_id",
      "description": "Merchant Center account ID"
    }
  ]
}

O que você pode pedir para ele fazer

Encontre e entenda problemas no catálogo

• Quais produtos estão reprovados e o que o Google relata para cada um deles?
• Mostre o título, o preço, a disponibilidade e o status atual do produto SKU-123.
• Quais produtos estão fora de estoque?
• Mostre os problemas de produto mais frequentes para esta conta do Merchant Center.

Explore desempenho e preços

• Mostre cliques e impressões por produto em julho.
• Quais produtos estão com preço acima do benchmark de mercado nos Estados Unidos?
• Quais preços o Google sugere e qual impacto ele prevê?

Comparações e sugestões de preço exigem a ativação gratuita do Market Insights no Merchant Center. Se a conta não tiver ativado, o servidor explica por que o relatório não tem linhas.

Inspecione a conta e os feeds

• Liste as contas do Merchant Center às quais tenho acesso.
• A página inicial da loja está reivindicada? Mostre as configurações de envio atuais.
• Liste as fontes de dados de produto e promoção e identifique uma fonte de dados de API.
• Busque novamente este feed de arquivo agendado agora.

Faça alterações deliberadas

• Atualize o preço e a disponibilidade deste produto na sua fonte de dados de API.
• Crie uma fonte de dados de API para um novo feed de produtos.
• Crie ou atualize uma promoção e depois verifique seu status de aprovação.

Para qualquer solicitação que altere dados, primeiro peça ao assistente para mostrar a conta de destino, a fonte de dados e os campos exatos que ele planeja alterar.

Como os dados do Merchant Center são conectados

O Merchant Center mantém os dados recebidos e o status do produto resultante separados:

1. Uma conta contém fontes de dados de produto e promoção.
2. Uma fonte de dados pode ser uma fonte de API, um arquivo, uma planilha do Google, a interface do Merchant Center ou um feed automático.
3. Uma entrada de produto são os dados do produto fornecidos por uma fonte.
4. Um produto processado é o que o Merchant Center deriva após processar essa entrada. Inclui elegibilidade e problemas no nível do item.

O servidor pode ler todos os tipos de fonte listados. Ele pode criar fontes de dados de API e atualizar entradas de produto somente em uma fonte de dados de API; ele não pode gravar em um arquivo, interface ou feed automático. Para encontrar produtos por condição, use uma consulta de relatório: list_products em si não fornece filtragem no lado do servidor.

O que pode mudar

O cliente MCP decide como pede confirmação para ferramentas de gravação e destrutivas. O servidor marca suas operações somente leitura, gravação e destrutivas para que o cliente possa apresentar o limite correto.

Obtendo acesso

O servidor usa a Google Merchant API e o escopo OAuth https://www.googleapis.com/auth/content. Há duas maneiras de fornecer credenciais a ele, e a primeira não precisa de arquivos de configuração.

Conecte-se pelo chat (recomendado)

Diga "conectar Google Merchant Center" e o assistente executa o fluxo com você:

1. setup_instructions imprime a lista de verificação: criar ou selecionar um projeto do Google Cloud, ativar a Merchant API, configurar a tela de consentimento e criar um cliente OAuth de aplicativo de desktop.
2. Baixe o JSON desse cliente ("Baixar JSON") e forneça o caminho ao assistente — set_client o armazena com acesso somente do proprietário. O segredo nunca passa pela conversa.
3. start_login retorna um link de consentimento do Google. Abra-o nesta máquina e aprove; o código volta para um ouvinte de uso único em 127.0.0.1 (PKCE), nunca pelo chat.
4. finish_login troca o código, salva os tokens em ~/.config/mcp-google-merchants/credentials.json (modo 0600) e os verifica com uma chamada real à Merchant API — assim, um projeto que ainda não está registrado no Merchant Center é detectado ali mesmo.

Os tokens são relidos a cada chamada, então a conexão funciona imediatamente — sem reiniciar o aplicativo de IA. auth_status mostra o que está conectado, logout revoga e exclui. O registro do projeto no Cloud abaixo ainda é necessário: é uma etapa do Merchant Center, não do OAuth.

Variáveis de ambiente (CI, instalações não assistidas)

1. Crie ou selecione um projeto do Google Cloud, ative a Merchant API e configure a tela de consentimento OAuth.
2. No Google Cloud, crie um cliente OAuth do tipo aplicativo de desktop. Salve o ID e o segredo do cliente.
3. Autorize a conta do Google que tem acesso ao seu Merchant Center e obtenha um token de atualização para o escopo acima. O OAuth 2.0 Playground pode ajudar nesta etapa: ative Usar minhas próprias credenciais OAuth, insira o escopo, autorize e troque o código por tokens.
4. Encontre o ID da sua conta do Merchant Center no Merchant Center e use-o como GOOGLE_MERCHANTS_ACCOUNT_ID.
5. Registre o projeto do Google Cloud no Merchant Center uma vez. O Google exige uma conta de produção do Merchant Center com um site verificado e um administrador de conta para esta operação. O registro vincula um projeto do Cloud à conta do Merchant Center; até que seja concluído, as chamadas à Merchant API desse projeto são bloqueadas. Siga o guia de registro para desenvolvedores do Google.

O registro único está disponível por meio da ferramenta técnica raw_request, mas é mais seguro seguir o guia do Google se esta for sua primeira configuração da Merchant API. O Google pode levar até cinco minutos para aceitar chamadas após o registro.

Trate o segredo do cliente OAuth e o token de atualização como senhas. Eles são mantidos na configuração do cliente MCP e podem conceder acesso à conta do Merchant Center.

Configuração

* Use o ID do cliente, o segredo do cliente e o token de atualização juntos, ou um token de acesso pré-gerado. Um token de acesso geralmente expira em cerca de uma hora; um token de atualização permite que o servidor obtenha um novo token de acesso quando necessário.

Dados e telemetria

O servidor é executado localmente como um processo iniciado pelo seu aplicativo de IA. Ele envia solicitações do Merchant Center ao Google e atualiza os tokens de acesso OAuth por meio do endpoint OAuth do Google.

Ele envia telemetria anônima de uso para contar instalações ativas e demanda por ferramentas: um ID de instalação aleatório, versão do pacote, cliente de IA e versões do Node.js/sistema operacional, e o nome da ferramenta. Ele nunca envia ou armazena tokens OAuth, dados do Merchant Center, argumentos de ferramentas ou prompts. Desative essa telemetria para servidores MCP A1 com:

ASKADS_TELEMETRY=0

Limites e trabalho em segundo plano

• O processamento do Merchant Center é assíncrono. Uma entrada de produto recém-inserida, atualizada ou excluída pode levar vários minutos para aparecer nos produtos processados. Problemas de aprovação de produtos e promoções aparecem depois, não como um erro imediato da API.
• O Market Insights é opcional. Os relatórios de competitividade de preços e preços sugeridos retornam dados somente após a conta optar pelo programa gratuito Market Insights.
• As cotas dependem da conta e do método da API. Verifique o consumo atual com list_method_quotas; os contadores diários do Google são redefinidos às 12:00 UTC.
• Limites temporários são tratados com cautela. Quando o Google retorna 429, o servidor segue Retry-After quando fornecido e faz um número limitado de tentativas. Ele não repete uma gravação após uma falha incerta de rede ou servidor.
• Não há monitoramento em segundo plano. O servidor funciona apenas enquanto um aplicativo de IA o chama. Se o seu aplicativo de IA suportar tarefas agendadas, você pode pedir que ele verifique problemas de produtos ou uso de cotas periodicamente.
• Problemas agregados de produtos têm uma limitação de conta. list_product_issues funciona para contas independentes e subcontas, não para contas pai avançadas.

Documentação técnica

• Catálogo de capacidades do MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas e suas entradas
• Documentação de desenvolvimento
• Documentação de publicação
• Visão geral da API Google Merchant
• Autenticação da API Google Merchant
• Registro de desenvolvedor do Google

Suporte

Encontrou um bug ou precisa de um cenário? Crie uma issue ou escreva no Telegram.

Você chegou ao fim!