google-workspace-mcp

MCP multicuenta y eficiente en el uso de tokens para Gmail + Calendar + Drive + Docs + Sheets. Creado porque el conector oficial de Claude admite una sola cuenta y devuelve el cuerpo completo de los mensajes/archivos de forma predeterminada.

Por qué existe esto

• Multicuenta: OAuth para múltiples buzones (trabajo + personal + cofundador). Cada herramienta requiere un correo electrónico de account; los alias se gestionan mediante identidades de envío (Send-As).

• Eficiente en tokens: Las búsquedas/listados devuelven formatos compactos ({id, from, subject, snippet, ...} para correo, {id, name, mime, modified, size, ...} para Drive). Los cuerpos y el contenido de los archivos son opcionales.

• Respaldado por el llavero (Keychain): Los tokens de actualización residen en el llavero de macOS, no en archivos de texto plano. Sin tokens en la bóveda, sin tokens en ningún repositorio.

Herramientas (v2, 61 herramientas)

Gestión de cuentas (3)

• gws_account_add — flujo OAuth en el navegador, añade un nuevo buzón autorizado

• gws_account_list — lista las cuentas autorizadas + la predeterminada

• gws_account_remove — elimina la credencial local (no revoca el acceso en Google)

Gmail (10)

• gmail_search — búsqueda con operadores de Gmail. Respuesta compacta.

• gmail_read — leer un mensaje o un hilo completo. Cuerpos opcionales.

• gmail_send — enviar correo, from_alias opcional para identidades de envío (Send-As)

• gmail_draft — crear un borrador

• gmail_reply — responder (conserva el hilo + encabezados), reply_all opcional

• gmail_labels_list — listar todas las etiquetas

• gmail_label_apply — añadir/eliminar etiquetas por lotes

• gmail_archive — archivar por lotes (eliminar de RECIBIDOS)

• gmail_trash — mover a la papelera por lotes

• gmail_sendas_list — listar identidades de envío (Send-As) en este buzón

Calendar (7)

• cal_list_calendars — listar todos los calendarios

• cal_list_events — listar próximos eventos (compacto por defecto, verbose=True para completo)

• cal_create_event — crear evento, enlace de Google Meet opcional

• cal_update_event — actualización parcial de campos

• cal_delete_event — eliminar

• cal_freebusy — comprobar ventanas de disponibilidad para programar

• cal_respond — aceptar/rechazar/tentativo

Drive (18)

• drive_search — texto libre o sintaxis q de Drive. Respuesta solo con metadatos.

• drive_read_file — metadatos por defecto; include_content=True para el cuerpo

• drive_list_folder — hijos directos de una carpeta ('root' para Mi unidad)

• drive_create_folder — crear una carpeta bajo un padre opcional

• drive_upload — subir un archivo local, convert_to_google opcional

• drive_move — cambiar carpeta padre

• drive_rename — renombrar un archivo o carpeta

• drive_share — otorgar acceso de lector/comentador/editor/etc. por correo

• drive_trash — eliminación suave (recuperable)

• drive_untrash — restaurar desde la papelera

• drive_permission_list — listar a todos los que tienen acceso a un archivo

• drive_permission_update — cambiar el rol de un usuario con acceso

• drive_permission_delete — revocar un permiso

• drive_shared_drives_list — listar unidades compartidas a las que accede esta cuenta

• drive_comments_list — listar comentarios en cualquier archivo de Drive (Doc/Sheet/Slide/subida)

• drive_comment_add — añadir un comentario, ancla opcional

• drive_comment_reply — responder a un comentario

• drive_comment_resolve — marcar un comentario como resuelto

Docs (9)

• docs_create — nuevo documento, cuerpo inicial y carpeta padre opcionales

• docs_read — texto plano por defecto; structured=True para el árbol completo de la API de Docs

• docs_append — añadir texto al final del cuerpo

• docs_insert_at — insertar texto en un índice específico

• docs_replace_text — buscar y reemplazar, devuelve el recuento de reemplazos

• docs_export — exportar a markdown / pdf / docx / rtf / texto plano

• docs_suggestions_list — listar sugerencias de cambios pendientes

• docs_suggestions_accept_all — aceptar todas las sugerencias (reescribe el documento)

• docs_suggestions_reject_all — rechazar todas las sugerencias (reescribe el documento)

Sheets (14)

• sheets_create — nuevo libro de trabajo, carpeta padre opcional

• sheets_list_sheets — listar pestañas con dimensiones de fila/columna

• sheets_add_sheet — añadir una nueva pestaña a un libro existente

• sheets_read_range — leer rango A1. Opciones FORMULA / UNFORMATTED_VALUE.

• sheets_write_range — sobrescribir un rango. USER_ENTERED analiza fórmulas.

• sheets_append — añadir filas debajo de los datos existentes

• sheets_clear_range — borrar valores (formato conservado)

• sheets_batch_read — lectura de múltiples rangos en una llamada a la API

• sheets_batch_write — escritura de múltiples rangos en una llamada a la API

• sheets_named_ranges_list — listar rangos con nombre en un libro

• sheets_named_range_add — crear un rango con nombre

• sheets_named_range_delete — eliminar un rango con nombre

• sheets_conditional_format_add — añadir una regla de formato condicional

• sheets_data_validation_add — establecer validación de desplegable / número / correo / URL

Instalación

Consulta SETUP.md para la configuración única de GCP (~45 min para v1, ~5 min adicionales para habilitar Drive/Docs/Sheets para v2).

Tras la configuración:

pip3 install --break-system-packages -r requirements.txt

Registrar con Claude Code

Añádelo al archivo .mcp.json de tu proyecto (o ~/.claude.json para acceso global):

"google-workspace": {
  "type": "stdio",
  "command": "python3",
  "args": ["/path/to/google-workspace-mcp/server.py"]
}

Actualización de v1 → v2

La v2 añade ámbitos de Drive + Docs + Sheets. Cada cuenta autorizada debe volver a realizar el OAuth una vez para que Google conceda los nuevos ámbitos. Consulta el paso 6b de SETUP.md.

Hoja de ruta

• v3: Filtros de Gmail, respuesta automática de vacaciones, notificaciones push (Gmail Watch), ACL/delegación de Calendar, Slides, Forms, Tasks

• v4: Solicitudes por lotes entre servicios, revisiones de Drive

Licencia

MIT