Conectar Claude Code a Google Workspace con cinco comprobaciones de lectura

Claude Code puede ejecutar comandos de Google Workspace CLI (gws) desde un shell local, usando la cuenta de Google autenticada en gws. El titular autorizado de la cuenta puede comprobar la conexión con un elemento inocuo de cada servicio: Drive, Sheets, Docs y Gmail. Primero confirma la cuenta y sus autorizaciones. Esta guía sigue la interfaz documentada del repositorio del CLI, examinada el 20 de octubre de 2026. BIG CHANGE no instaló ninguna de las dos herramientas ni accedió a una cuenta.

El gran cambio

• Qué cambió: El CLI gws actual expone métodos de las API de Google Workspace como comandos de shell que Claude Code puede ejecutar. Una cuenta autenticada puede dar acceso a varios servicios de trabajo, según sus autorizaciones reales y los permisos del shell del agente.
• Por qué importa: La misma conexión que permite al agente consultar un archivo o mensaje seleccionado puede alcanzar otros datos cubiertos por sus ámbitos OAuth. El titular puede comparar resultados pequeños y conocidos en el terminal y en Claude Code antes de delegar más trabajo.
• Qué vigilar: Comprueba los comandos generados por el CLI instalado y las reglas de permiso efectivas de la sesión cada vez que cambie la configuración. El CLI es anterior a la versión 1.0; una consulta de ejemplo limitada o una máscara de campos no reduce la autorización de toda la cuenta.

Antes de conectarte

Usa una cuenta de pruebas de Google dedicada y aprobada, sin contenido sensible, y un proyecto Cloud donde puedas configurar OAuth. Pregunta al administrador si están permitidas las cuatro API y las autorizaciones solicitadas. Prepara un archivo existente de Drive con nombre único, una hoja de cálculo con valores conocidos en un intervalo pequeño, un Google Doc breve de texto sin formato con una sola pestaña y un mensaje inocuo de Gmail. Para Gmail, obtén su identificador RFC Message-ID desde Show original. Compararás estos originales con los resultados del CLI. Estas comprobaciones no crean ni envían nada.

Instala Claude Code en un equipo controlado. Instala gws desde la versión del repositorio para tu sistema operativo o, con Node.js 18 o posterior, utiliza el comando documentado:

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

Registra en privado las versiones instaladas del CLI y de Claude Code. El CLI sigue siendo anterior a la versión 1.0 y construye sus comandos a partir de los documentos de descubrimiento de las API de Google. Consulta la ayuda instalada y los esquemas de los métodos siguientes antes de ejecutar los ejemplos.

1. Configura un inicio de sesión OAuth limitado

En el proyecto Cloud aprobado, habilita las API de Drive, Sheets, Docs y Gmail. Configura el público de OAuth y crea un cliente Desktop app. Si la aplicación es External y está en pruebas, añade la cuenta elegida como usuario de prueba. Guarda el JSON descargado del cliente en la ubicación documentada ~/.config/gws/client_secret.json o usa un directorio independiente seleccionado con GOOGLE_WORKSPACE_CLI_CONFIG_DIR. Mantén ese directorio fuera del proyecto Claude y privado para el titular de la cuenta.

Antes de iniciar sesión, comprueba en privado si GOOGLE_WORKSPACE_CLI_TOKEN o GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE está definida, incluso mediante un archivo .env. Estas fuentes tienen prioridad sobre las credenciales OAuth almacenadas. No muestres sus valores ni pidas a Claude Code que lea archivos de credenciales. Usa un entorno limpio y la configuración del cliente prevista.

Solicita explícitamente estos cuatro ámbitos:

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

Selecciona la cuenta y da el consentimiento personalmente. El código del CLI en la revisión indicada también añade los ámbitos de identidad openid, userinfo.email y userinfo.profile. Compara en privado el consentimiento y los datos de gws auth status sobre cuenta, autorizaciones y validez del token con lo que pretendías; un campo de estado ausente sigue sin verificarse. Detente si la cuenta es incorrecta o persiste una autorización más amplia e inesperada. Seleccionar servicios en el selector de inicio de sesión filtra las opciones; no establece estos cuatro ámbitos de solo lectura.

Los ámbitos son más amplios que las solicitudes de ejemplo. El acceso a metadatos de Drive alcanza los metadatos de archivos accesibles; el acceso de solo lectura de Sheets y Docs cubre hojas y documentos accesibles; Gmail de solo lectura puede acceder al contenido del buzón. Nombres, identificadores, intervalos, consultas y máscaras de campos limitan cada respuesta, no la autoridad del token. Una herramienta de shell también puede alcanzar credenciales locales; una ruta oculta o una instrucción en un prompt no las aísla.

2. Ejecuta directamente las lecturas limitadas

Primero examina cada método con gws schema drive.files.list y los nombres de esquema correspondientes de los demás métodos. Consulta la ayuda generada --help si un parámetro difiere en tu versión instalada. Los comandos siguientes usan comillas simples de Bash; adapta expresamente las comillas para otro shell. Sustituye solo los identificadores y el nombre de prueba. Ejecuta un comando cada vez y conserva en privado su respuesta o error real, sin tokens ni contenido sensible.

Busca el archivo de Drive por su nombre. La secuencia JSON \u0027 escapa los apóstrofos de la expresión de búsqueda de Drive conservando las comillas de Bash:

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

Compara su identificador y nombre con el archivo en Drive. No encontrar una coincidencia o recibir incompleteSearch no demuestra acceso al archivo previsto.

Lee las celdas conocidas con el identificador real de la hoja de cálculo y el nombre de la pestaña:

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

Compara los valores devueltos con la hoja. Google puede omitir celdas vacías finales, así que prepara valores conocidos que no estén vacíos.

Lee la primera pestaña del documento de prueba breve:

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

Comprueba el identificador, el título y el texto conocido. Esta respuesta limitada no comprueba otras pestañas, comentarios ni la estructura completa del documento.

En Gmail, busca el mensaje existente por su identificador RFC Message-ID y usa después el identificador de Gmail devuelto para solicitar dos cabeceras:

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)"}'

Compara el Message-ID devuelto y el asunto inocuo con el original. La primera llamada devuelve identificadores de mensajes, no cabeceras. La segunda solicita metadatos de cabecera, no el cuerpo del mensaje. Una primera respuesta vacía no permite la segunda comprobación. El ámbito OAuth de metadatos de Gmail, más limitado, no permite la consulta de búsqueda usada aquí; la autorización explícita de Gmail de solo lectura sí.

3. Repite con Claude Code y las solicitudes de permiso

Inicia Claude Code en un proyecto que controles, con la misma configuración de cuenta aprobada. En /permissions, examina el modo efectivo y las reglas del shell. Usa Manual (también llamado default) y una regla Ask para la herramienta de shell real; resuelve cualquier regla más amplia de autorización o de omisión de controles según la política de tu organización. Evita la autorización general para gws * o para un programa que envuelva el shell. Ante cada comando propuesto, examina el comando completo y aprueba solo la lectura limitada que pretendes.

Pide a Claude Code en lenguaje natural que proponga los cinco comandos anteriores con los mismos elementos de prueba y los ejecute uno a uno solo después de tu decisión de permiso. Solicita la salida o los errores sin leer credenciales, ampliar consultas ni realizar escrituras. Después compara cada resultado con el resultado directo y el objeto original. Las instrucciones del proyecto pueden describir la tarea, pero los permisos efectivos de las herramientas y las autorizaciones OAuth determinan el acceso.

Registra versiones, cuenta autenticada, autorizaciones reales, identificadores de destino, resultado directo, resultado de Claude y errores en una hoja de comprobación privada. Una solicitud fallida, una respuesta correcta pero vacía y un objeto verificado son resultados diferentes. Termina solo cuando los cuatro servicios estén verificados por ambas vías.

Si falla una comprobación

Un error Access blocked al iniciar sesión puede indicar que falta la cuenta de prueba en la lista de usuarios de prueba de la aplicación OAuth. Ante un error de API o ámbito, confirma la API habilitada, la cuenta elegida y las autorizaciones reales antes de solicitar un nuevo consentimiento aprobado. Para una lista vacía, comprueba el destino exacto, la consulta y la cuenta. Si la ayuda instalada difiere de estos ejemplos, usa el esquema actual del método antes de continuar. Si Claude Code propone un comando que modifique datos o amplíe el acceso, recházalo en la solicitud de permiso y vuelve a la lectura limitada.

El repositorio del CLI está disponible sin un paquete de pago. La cuenta o el plan Workspace, las cuotas Cloud y el plan Claude Code o el uso de su API pueden generar costes. El proveedor configurado en Claude Code puede procesar el contenido recuperado: usa datos de prueba no sensibles y aprobados. El CLI indica que no es un producto de Google con soporte oficial y advierte de cambios anteriores a la versión 1.0. BIG CHANGE no ha probado el rendimiento ni la compatibilidad. Detente antes de cualquier escritura, envío o cambio de cuenta. El complemento independiente de Google Workspace de Claude permite editar archivos abiertos con aprobación por otra vía.