Sheets Connector

Lê e escreve dados no Google Sheets diretamente a partir do agente. Transforme planilhas em fonte e destino de dados do seu fluxo com o Claude Code: consulte linhas, gere resumos, registre novos resultados e atualize células — tudo por linguagem natural.

O que faz

O Sheets Connector liga o agente à API do Google Sheets usando uma conta de serviço (service account), permitindo automatizar tarefas de planilha sem trabalho manual repetitivo.

Casos de uso típicos:

• Ler e analisar: carregar um intervalo de linhas, entender o cabeçalho e gerar um resumo, total, média ou ranking.
• Registrar resultados: acrescentar novas linhas ao fim de uma planilha (logs de execução, leads, métricas, status de tarefas).
• Atualizar células: corrigir ou completar valores em linhas existentes localizadas por uma coluna-chave.
• Exportar dados estruturados: converter o resultado de uma conversa (lista de itens, decisões, tarefas) em linhas tabulares.
• Validar dados: apontar células vazias, formatos inconsistentes ou duplicatas em uma coluna.

O plugin sempre detecta o cabeçalho da primeira linha para mapear nomes de coluna a posições (A, B, C...), evitando que você precise lidar com índices manualmente.

Instalação

Pelo marketplace do Claude Code:

/plugin marketplace add aulasdeia/plugins
/plugin install sheets-connector

Ou a partir do diretório local:

/plugin install ./library/plugins/sheets-connector

Reinicie a sessão para que os comandos /sheets:* apareçam.

Comandos disponíveis

• /sheets:read — Lê um intervalo (ou aba inteira) da planilha e produz um resumo/análise do que foi pedido.
• /sheets:write — Acrescenta novas linhas ou atualiza linhas existentes (localizadas por coluna-chave) na planilha.

Os comandos delegam a operação ao subagente sheets-operator, especialista na API do Google Sheets v4.

Configuração

Defina as variáveis de ambiente abaixo. Use apenas os nomes — nunca cole o JSON da chave ou IDs em arquivos versionados.

• GOOGLE_SERVICE_ACCOUNT_JSON — Caminho para (ou conteúdo do) arquivo JSON da conta de serviço do Google Cloud, com a API do Google Sheets habilitada.
• GOOGLE_SHEETS_SPREADSHEET_ID — ID da planilha alvo. É o trecho da URL entre /d/ e /edit.

Exemplo de .env (sem valores reais):

GOOGLE_SERVICE_ACCOUNT_JSON=
GOOGLE_SHEETS_SPREADSHEET_ID=

Passos para preparar o acesso:

1. No Google Cloud Console, crie uma conta de serviço e gere uma chave JSON.
2. Habilite a Google Sheets API no projeto.
3. Compartilhe a planilha alvo com o e-mail da conta de serviço ([email protected]), concedendo permissão de Editor se for escrever, ou Leitor se for apenas ler.

Exemplo de uso

Ler e resumir:

/sheets:read Aba "Leads": quantos leads chegaram este mês e quais as 3 origens mais comuns?

O agente vai detectar o cabeçalho, ler o intervalo, contar e devolver o resumo com números.

Escrever uma nova linha:

/sheets:write Acrescente na aba "Execucoes": data=hoje, tarefa="deploy aulasdeia", status="ok"

O agente mapeia os campos às colunas pelo cabeçalho, monta a linha na ordem correta e a acrescenta ao fim, confirmando a operação.

Segurança e limites

• O JSON da conta de serviço em GOOGLE_SERVICE_ACCOUNT_JSON é uma credencial poderosa: trate-o como segredo, nunca o exiba em logs nem o versione. Aplique o princípio do menor privilégio (compartilhe só as planilhas necessárias).
• A conta de serviço só acessa planilhas explicitamente compartilhadas com seu e-mail.
• A API do Google Sheets aplica cotas (por padrão, ~60 requisições de leitura e 60 de escrita por minuto por usuário). Para grandes volumes, o agente agrupa operações em lote (batchUpdate/batchGet).
• O comando /sheets:write mostra um pré-visualização das linhas a inserir/alterar e pede confirmação antes de modificar dados existentes.
• Atualizações por coluna-chave nunca apagam linhas inteiras sem confirmação explícita; o padrão é acrescentar, não sobrescrever.