Conecte o Claude Code ao Google Workspace com cinco verificações de leitura

O Claude Code pode executar comandos do Google Workspace CLI (gws) em um shell local, usando a conta Google autenticada no gws. O titular autorizado da conta pode verificar a conexão com um registro inofensivo em cada serviço: Drive, Sheets, Docs e Gmail. Primeiro, confirme a conta e as autorizações. Este guia segue a interface documentada do repositório do CLI, examinada em 20 de outubro de 2026. O BIG CHANGE não instalou nenhuma das duas ferramentas nem acessou uma conta.

A grande mudança

• O que mudou: O CLI gws atual disponibiliza métodos das APIs do Google Workspace como comandos de shell que o Claude Code pode executar. Uma conta autenticada pode oferecer acesso a vários serviços de trabalho, sujeito às autorizações reais e às permissões de shell do agente.
• Por que isso importa: A mesma conexão que permite ao agente consultar um arquivo ou mensagem selecionada pode alcançar outros dados cobertos pelos escopos OAuth. O titular pode comparar resultados pequenos e conhecidos no terminal e no Claude Code antes de decidir delegar mais trabalho.
• O que observar: Confira os comandos gerados pelo CLI instalado e as regras de permissão efetivas da sessão sempre que essa configuração mudar. O CLI ainda é anterior à versão 1.0; uma consulta de exemplo restrita ou uma máscara de campos não reduz a autorização da conta inteira.

Antes de conectar

Use uma conta de teste Google dedicada e aprovada, sem conteúdo sensível, e um projeto Cloud em que você possa configurar OAuth. Pergunte ao administrador se as quatro APIs e as autorizações solicitadas são permitidas. Prepare um arquivo existente no Drive com nome único, uma planilha com valores conhecidos em um pequeno intervalo, um Google Doc curto de texto simples com uma única aba e uma mensagem inofensiva no Gmail. Para o Gmail, obtenha o identificador RFC Message-ID em Show original. Você comparará esses originais com os resultados do CLI. As verificações não criam nem enviam nada.

Instale o Claude Code em um computador controlado. Instale gws a partir da versão do repositório para seu sistema operacional ou, com Node.js 18 ou posterior, use o comando documentado:

npm install -g @googleworkspace/cli
gws --version
gws --help
gws auth login --help

Registre em particular as versões instaladas do CLI e do Claude Code. O CLI ainda é anterior à versão 1.0 e gera seus comandos a partir dos documentos de descoberta das APIs do Google. Confira a ajuda instalada e os esquemas dos métodos abaixo antes de executar os exemplos.

1. Configure um login OAuth restrito

No projeto Cloud aprovado, ative as APIs do Drive, Sheets, Docs e Gmail. Configure o público do OAuth e crie um cliente Desktop app. Se o aplicativo for External e estiver em teste, adicione a conta escolhida como usuário de teste. Salve o JSON baixado do cliente no local documentado ~/.config/gws/client_secret.json ou use um diretório separado selecionado com GOOGLE_WORKSPACE_CLI_CONFIG_DIR. Mantenha esse diretório fora do projeto Claude e acessível somente ao titular da conta.

Antes de entrar, verifique em particular se GOOGLE_WORKSPACE_CLI_TOKEN ou GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE está definida, inclusive por meio de um arquivo .env. Essas fontes têm prioridade sobre as credenciais OAuth armazenadas. Não exiba os valores nem peça ao Claude Code para ler arquivos de credenciais. Use um ambiente limpo e a configuração de cliente pretendida.

Solicite explicitamente estes quatro escopos:

gws auth login --scopes 'https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/gmail.readonly'
gws auth status

Faça pessoalmente a seleção da conta e o consentimento. O código-fonte do CLI na revisão indicada também adiciona os escopos de identidade openid, userinfo.email e userinfo.profile. Compare em particular o consentimento e as informações de gws auth status sobre conta, autorizações e validade do token com o que pretendia; um campo de status ausente continua sem verificação. Pare se a conta estiver errada ou restar uma autorização inesperada mais ampla. Selecionar serviços na tela de login filtra opções; isso não define os quatro escopos de somente leitura.

Os escopos são mais amplos que as solicitações de exemplo. O acesso aos metadados do Drive alcança metadados dos arquivos acessíveis; o acesso de somente leitura do Sheets e Docs abrange planilhas e documentos acessíveis; o Gmail de somente leitura pode acessar o conteúdo da caixa postal. Nomes, IDs, intervalos, consultas e máscaras de campos limitam cada resposta, não a autoridade do token. Uma ferramenta de shell também pode alcançar credenciais locais; ocultar um caminho ou escrever uma instrução no prompt não as isola.

2. Execute diretamente as leituras delimitadas

Primeiro examine cada método com gws schema drive.files.list e os nomes de esquema correspondentes dos demais métodos. Consulte a ajuda gerada --help se algum parâmetro for diferente na versão instalada. Os comandos abaixo usam aspas simples do Bash; adapte as aspas de propósito para outro shell. Substitua apenas os identificadores e o nome de teste. Execute um comando por vez e retenha a resposta ou o erro real em particular, sem tokens nem conteúdo sensível.

Localize o arquivo do Drive pelo nome. A sequência JSON \u0027 escapa os apóstrofos na expressão de busca do Drive preservando as aspas do Bash:

gws drive files list --params '{"pageSize":5,"q":"trashed = false and name = \u0027GWS connection check\u0027","fields":"files(id,name,mimeType),nextPageToken,incompleteSearch"}'

Compare o ID e o nome com o arquivo no Drive. Uma correspondência ausente ou incompleteSearch não comprova acesso ao arquivo pretendido.

Leia as células conhecidas usando o ID real da planilha e o nome da aba:

gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C3","fields":"range,majorDimension,values"}'

Compare os valores retornados com a planilha. O Google pode omitir células vazias ao final; prepare valores conhecidos não vazios.

Leia a primeira aba do documento de teste curto:

gws docs documents get --params '{"documentId":"DOCUMENT_ID","includeTabsContent":false,"fields":"documentId,title,body(content(paragraph(elements(textRun(content)))))"}'

Confira o ID, o título e o texto conhecido. Essa resposta limitada não verifica outras abas, comentários ou a estrutura completa do documento.

No Gmail, busque pelo identificador RFC Message-ID da mensagem existente e use o ID do Gmail retornado para solicitar dois cabeçalhos:

gws gmail users messages list --params '{"userId":"me","maxResults":1,"q":"rfc822msgid:MESSAGE_ID_FROM_SHOW_ORIGINAL","fields":"messages(id,threadId),nextPageToken,resultSizeEstimate"}'
gws gmail users messages get --params '{"userId":"me","id":"GMAIL_MESSAGE_ID","format":"metadata","metadataHeaders":["Message-ID","Subject"],"fields":"id,threadId,payload(headers)"}'

Compare o Message-ID retornado e o assunto inofensivo com o original. A primeira chamada retorna IDs de mensagens, não cabeçalhos. A segunda solicita metadados dos cabeçalhos, não o corpo da mensagem. Uma primeira resposta vazia não permite a segunda verificação. O escopo OAuth mais restrito de metadados do Gmail não permite a consulta de busca usada aqui; a autorização explícita de somente leitura do Gmail permite.

3. Repita pelo Claude Code com pedidos de permissão

Inicie o Claude Code em um projeto sob seu controle, com a mesma configuração de conta aprovada. Em /permissions, examine o modo efetivo e as regras do shell. Use Manual (também chamado default) e uma regra Ask para a ferramenta de shell real; resolva regras mais amplas de autorização ou desvio de controles conforme a política da organização. Evite aprovação geral para gws * ou para um programa que envolva o shell. A cada comando proposto, confira o comando completo e aprove apenas a leitura delimitada pretendida.

Peça ao Claude Code, em linguagem comum, que proponha os cinco comandos acima com os mesmos alvos de teste e os execute um por vez, somente após sua decisão de permissão. Solicite a saída ou os erros sem ler credenciais, ampliar consultas ou executar gravações. Compare cada resultado com o resultado direto e com o objeto original. As instruções do projeto podem descrever a tarefa, mas as permissões efetivas das ferramentas e as autorizações OAuth determinam o acesso.

Registre versões, conta autenticada, autorizações reais, IDs dos alvos, resultado direto, resultado do Claude e erros em uma ficha privada. Uma solicitação que falhou, uma resposta bem-sucedida vazia e um objeto verificado são resultados diferentes. Conclua apenas quando os quatro serviços forem verificados pelas duas rotas.

Se uma verificação falhar

Um erro Access blocked no login pode significar que falta a conta na lista de usuários de teste do aplicativo OAuth. Em caso de erro de API ou escopo, confirme a API ativada, a conta selecionada e as autorizações reais antes de pedir um novo consentimento aprovado. Para uma lista vazia, confira o alvo exato, a consulta e a conta. Se a ajuda instalada diferir destes exemplos, use o esquema atual do método antes de continuar. Se o Claude Code propuser um comando que altere dados ou amplie o acesso, recuse no pedido de permissão e retorne à leitura delimitada.

O repositório do CLI está disponível sem um pacote pago. A conta ou o plano Workspace, as cotas Cloud e o plano Claude Code ou o uso da API podem gerar custos. O conteúdo obtido pode ser processado pelo provedor configurado no Claude Code; mantenha os testes em dados aprovados e não sensíveis. O CLI informa que não é um produto Google com suporte oficial e alerta sobre mudanças anteriores à versão 1.0. O BIG CHANGE não testou desempenho ou compatibilidade. Pare antes de qualquer gravação, envio ou alteração da conta. O complemento separado do Google Workspace do Claude trata da edição de arquivos abertos com aprovação por outra rota.