Servidor MCP de dados do comerciante (Alfa público)

Receba dados em tempo real sobre sua conta do Merchant Center diretamente do assistente de programação da sua preferência. No ambiente de desenvolvimento integrado (IDE, na sigla em inglês) ou na estrutura de agente personalizado, agora é possível acessar e gerenciar os dados do Merchant Center usando o serviço do Protocolo de Contexto de Modelo (MCP, na sigla em inglês). Esse serviço permite que o assistente ou agente de programação realize operações de leitura e gravação seguras nos dados do Merchant Center, permitindo que ele diagnostique problemas, verifique programas e consulte relatórios com contexto autorizado e em tempo real.

Para mais informações sobre o protocolo, consulte o padrão do Protocolo de Contexto de Modelo.

Segurança e controle de acesso

O servidor MCP de dados do Merchant foi projetado com a segurança como prioridade:

  • Autenticação: a execução da ferramenta é estritamente regida pela autenticação padrão da API Merchant, que exige credenciais do OAuth 2.0 ou da conta de serviço.
  • Segurança de execução: apesar da ampla visibilidade dos esquemas de ferramentas para o agente, a execução real de qualquer ferramenta permanece altamente segura e é estritamente restrita pelas suas credenciais de API específicas.

Considerações importantes

Antes de usar essas ferramentas, revise as práticas recomendadas e limitações a seguir:

Mudanças e lançamentos

Vamos postar sobre as mudanças nas notas de lançamento, mas elas podem acontecer imediatamente, sem um período de suspensão.

Testes seguros

Recomendamos que você faça testes primeiro usando uma conta de teste ou uma conta não ativa antes de usar essas ferramentas em um ambiente de produção ativo.

Cota compartilhada

O servidor MCP compartilha o mesmo pool de cotas que as chamadas padrão da API Merchant. A execução de agentes pode esgotar rapidamente a cota, especialmente para buscas de origem de dados. Recomendamos o uso de uma conta de teste para evitar interrupções no serviço de produção.

Filtragem e segurança de ferramentas

O Google poderá adicionar novas ferramentas (incluindo recursos de gravação) a esse servidor MCP no futuro. Para evitar que o agente de IA execute automaticamente e sem querer ferramentas novas ou arriscadas, recomendamos fortemente configurar explicitamente o cliente para a filtragem de ferramentas integrada em vez de expor todo o conjunto de ferramentas.

Escopo e limitações

  • Foco somente leitura: como uma proteção para essa fase inicial, as ferramentas são estritamente limitadas a operações somente leitura e ferramentas de gravação de baixo risco (como a criação de origem de dados).

Recursos disponíveis

É possível usar o servidor MCP de dados do Merchant para realizar as seguintes ações de maneira agenciada:

  • Recupere o status detalhado e o contexto de relatórios de produtos específicos usando nomes de recursos exatos.
  • Liste e pesquise vários produtos.
  • Consulte dados de performance, status de produtos e informações de preço em relatórios de pesquisa.
  • Liste, crie, busque e verifique o status de upload das origens de dados.
  • Identifique problemas no nível da conta que afetam a visibilidade do produto ou a participação no programa.
  • Liste os motivos agregados para reprovações de produtos no seu inventário.
  • Verifique as regiões ativas, os requisitos não atendidos e o estado de participação de programas específicos do Merchant Center.
  • Analise as configurações de melhoria automática de itens, imagens e frete.

Configuração

Para conectar o IDE ou o assistente de programação ao servidor MCP de dados do Merchant, atualize as configurações do cliente MCP. Por exemplo, atualize o arquivo mcp.json para o Claude Desktop, Antigravity, Visual Studio Code ou sua estrutura de agente personalizado.

A configuração do servidor MCP local exige uma conta de serviço. O OAuth de usuário padrão não é compatível com essa execução local sem interface. É necessário criar uma conta de serviço, fazer o download do arquivo de chave privada JSON e fornecer o caminho para ele junto com seu ID específico do Merchant Center como argumentos.

Para instruções detalhadas sobre como criar e fazer o download de uma conta de serviço, consulte o guia Contas de serviço.

Configuração do cliente

Configurações:

Antigravity

Siga as instruções na Antigravity documentação.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Claude Desktop

Siga as instruções na documentação do Claude Desktop.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Exemplos de cenários de uso

O servidor MCP de dados do Merchant permite que o agente interaja com os dados ativos do Merchant Center. Veja algumas situações comuns:

Cenário 1: diagnosticar reprovações de produtos

Você quer entender por que um produto específico não aparece nos resultados da Pesquisa Google.

Comando do usuário:

"Por que meu produto com o ID da oferta 'offer123' foi reprovado?"

Comportamento do agente com o MCP:

  1. O agente chama list_products ou get_product_by_name para localizar o status do produto.
  2. O servidor MCP retorna o status do produto, incluindo uma lista de issues (por exemplo, "Formato de preço incorreto" ou "Valor de frete ausente").
  3. O agente analisa os problemas e explica a causa raiz, sugerindo como corrigir (por exemplo, atualizando as informações de preço).

Cenário 2: verificar melhorias automáticas

Você quer verificar se a otimização automática de envio está ativa.

Comando do usuário:

A otimização automática de envio está ativada?

Comportamento do agente com o MCP:

  1. O agente chama get_automatic_improvements para recuperar as configurações no nível da conta.
  2. O servidor MCP retorna a configuração mostrando o status das melhorias de imagem, item e frete.
  3. O agente confirma que as melhorias de frete estão ativas ou explica como ativá-las se estiverem desativadas.

Cenário 3: consultar métricas de performance

Você quer verificar rapidamente sua performance recente sem navegar na interface do Merchant Center.

Comando do usuário:

"Mostre meus cinco produtos com melhor performance por cliques na semana passada."

Comportamento do agente com o MCP:

  1. O agente cria uma consulta da Linguagem de consulta do Merchant Center (MCQL, na sigla em inglês) direcionada à tabela product_performance_view, ordenando por clicks DESC e limitando a 5.
  2. O agente chama report_search com a consulta criada.
  3. O servidor MCP executa a consulta no banco de dados de relatórios ativos e retorna as linhas.
  4. O agente formata os resultados em uma tabela Markdown limpa para você.

Lista detalhada de ferramentas disponíveis

O servidor MCP expõe as seguintes ferramentas ao agente:

Ferramenta MCP Descrição
get_product_by_name Receba informações do produto para um determinado comerciante usando o nome exato do recurso do produto. Retorna o status detalhado do produto contendo o contexto de relatórios e possíveis problemas no nível do produto.
list_products Liste ou pesquise vários produtos para um determinado comerciante. Retorna o status detalhado do produto contendo o contexto de relatórios e possíveis problemas no nível do produto.
report_search Consulte tabelas de relatórios para recuperar métricas de performance, status de produtos e informações de preço. Consulte o guia Relatórios para mais detalhes.
list_data_sources Liste as origens de dados de um determinado comerciante.
get_data_source Receba detalhes de uma origem de dados específica.
create_data_source Crie uma origem de dados para um determinado comerciante.
fetch_data_source Busque e processe o arquivo associado a uma origem de dados de um determinado comerciante.
get_file_upload Receba o status do upload de arquivo mais recente para uma determinada origem de dados.
list_accounts Liste as contas de um determinado usuário.
list_account_issues Liste os problemas no nível da conta de um determinado comerciante para identificar problemas em toda a conta.
list_programs Liste os programas de um determinado comerciante, incluindo o estado de participação, as regiões ativas e os requisitos não atendidos.
list_aggregated_product_issues Liste os problemas agregados no nível do produto para monitorar a integridade geral dos dados do produto.
get_automatic_improvements Receba as configurações de melhorias automáticas, incluindo atualizações de itens, melhorias de imagem e melhorias de frete.