Google Workspace MCP Server

Servidor MCP de Google Workspace

Este servidor de Protocolo de Contexto de Modelo (MCP) te permite controlar tu Google Workspace. Una vez que conectes tu cuenta (un proceso sencillo y seguro que solo toma un minuto), estarás listo para empezar. En segundo plano, mantiene tu conexión segura y activa, para que puedas concentrarte en tus tareas en lugar de gestionar inicios de sesión y permisos.

Controla tu bandeja de entrada de Gmail como nunca antes. ¿Quieres esa propuesta del trimestre pasado? La encontrarás en segundos. ¿Llevas demasiados boletines? Se organizarán automáticamente en carpetas. ¿Necesitas hacer un seguimiento de las respuestas a un hilo importante? Las etiquetas y los filtros lo hacen por ti. Desde redactar el correo electrónico perfecto hasta gestionar las conversaciones con tu equipo, todo encaja a la perfección. Con la gestión optimizada de archivos adjuntos, puedes encontrarlos y gestionarlos fácilmente mientras el sistema se encarga de todos los metadatos complejos en segundo plano.

Tu calendario se convierte en un aliado de confianza en el día a día. Se acabaron las reuniones duplicadas y la confusión horaria. ¿Planeas sincronizar a tu equipo? Encuentra las franjas horarias perfectas. ¿Organizas un taller recurrente? Configúralo una vez y listo. Incluso cuando cambian los planes, encontrar nuevos horarios que funcionen para todos es rápido y sencillo. Se acabaron los correos electrónicos interminables de "¿cuándo estás libre?".

Convierte Google Drive de un simple depósito de archivos en tu centro de control digital. Cada documento encuentra su lugar, cada carpeta cuenta una historia. Comparte archivos con las personas adecuadas: se acabó la confusión de "¿quién puede editar esto?". ¿Buscas la presentación de la reunión de la semana pasada? Busca no solo nombres, sino también el contenido de tus archivos. Ya sea que estés organizando un pequeño proyecto o gestionando una montaña de documentos, todo se mantiene justo donde lo necesitas.

Configuración TL;DR

Nota : Para asistentes de IA como Cline, consulte llms-install.md para obtener una guía de instalación especializada.

1. Crear un proyecto de Google Cloud:
   # Go to Google Cloud Console https://console.cloud.google.com → Create Project → Enable Gmail API and Calendar API → Configure OAuth consent screen (External) → Create OAuth Desktop Client ID and Secret
2. Agregar a la configuración de Cline (por ejemplo, ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ):
   { "mcpServers": { "google-workspace-mcp": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/home/aaron/.mcp/google-workspace-mcp:/app/config", "-v", "/home/aaron/Documents/workspace-mcp-files:/app/workspace", "-e", "GOOGLE_CLIENT_ID", "-e", "GOOGLE_CLIENT_SECRET", "-e", "LOG_MODE=strict", "ghcr.io/aaronsb/google-workspace-mcp:latest" ], "env": { "GOOGLE_CLIENT_ID": "123456789012-abcdef3gh1jklmn2pqrs4uvw5xyz6789.apps.googleusercontent.com", "GOOGLE_CLIENT_SECRET": "GOCSPX-abcdefghijklmnopqrstuvwxyz1234" }, "autoApprove": [], "disabled": false } } }
   Modos de registro:
   • normal (predeterminado): utiliza métodos de consola apropiados para cada nivel de registro
   • strict : enruta todos los mensajes que no sean JSON-RPC a stderr (recomendado para el escritorio Claude)
3. Reiniciar Cline/Claude
4. Simplemente pídale a la IA que "agregue mi cuenta de Google" y lo guiará a través del proceso de autenticación de forma conversacional.

Consulte la guía de configuración detallada para obtener más información.

Prerrequisitos

Importante:
Antes de iniciar el servidor MCP, debe crear usted mismo el directorio de configuración (por ejemplo, ~/.mcp/google-workspace-mcp ) y asegurarse de que sea propiedad de su cuenta de usuario.
Si este directorio falta o es propiedad de root, el servidor no podrá crear ni actualizar archivos de configuración y no podrá iniciarse.

Antes de utilizar este servidor MCP, debe configurar su propio proyecto de Google Cloud con acceso a las API de Google Workspace:

1. Crear un nuevo proyecto en Google Cloud Console
2. Habilite las API requeridas:
   • API de Gmail
   • API de Google Calendar
   • API de Google Drive
3. Configurar la pantalla de consentimiento de OAuth:
   • Configurar como "Externo"
   • Agreguese como usuario de prueba
   • Agregar los ámbitos requeridos para Gmail, Calendario y Drive
4. Crear credenciales OAuth 2.0:
   • Elija el tipo "Aplicación de escritorio"
   • Anote su ID de cliente y su secreto de cliente
   • Utilice "urn:ietf:wg:oauth:2.0:oob" como URI de redireccionamiento (esto habilita la autenticación fuera de banda)

El servidor MCP requiere:

1. Su ID de cliente de Google OAuth y su secreto de los pasos anteriores
2. Ruta del directorio local para almacenar la configuración (recomendado: ~/.mcp/google-workspace-mcp )

Nota: Este servidor utiliza un flujo de autenticación fuera de banda (OOB), lo que significa que deberá copiar y pegar manualmente los códigos de autorización durante la configuración inicial de cada cuenta.

Uso con Cline

Agregue la siguiente configuración a la configuración de Cline MCP:

Gestión de archivos

El servidor gestiona automáticamente los archivos de forma estructurada:

WorkspaceManager crea y mantiene esta estructura automáticamente:

• Crea directorios según sea necesario cuando se descargan o cargan archivos
• Organiza los archivos por correo electrónico del usuario
• Maneja la limpieza de archivos temporales
• Mantiene los permisos adecuados

Puede personalizar la ubicación del espacio de trabajo configurando la variable de entorno WORKSPACE_BASE_PATH .

Uso manual

Importante:
El directorio de configuración que monte (por ejemplo, ~/.mcp/google-workspace-mcp ) debe existir y ser propiedad de su usuario antes de iniciar el contenedor.
Si no existe, créelo con mkdir -p ~/.mcp/google-workspace-mcp && chown $USER ~/.mcp/google-workspace-mcp .
El servidor intentará crear accounts.json automáticamente si falta, pero solo si tiene acceso de escritura al directorio.

Puedes ejecutar el contenedor directamente:

El servidor automáticamente:

• Crear y administrar todos los archivos de configuración necesarios
• Gestionar el almacenamiento seguro de credenciales y tokens
• Mantener los permisos de archivo adecuados

Construcción de desarrollo

Script de compilación local

Para una compilación local rápida, similar a CI, y la creación de una imagen Docker, utilice el script proporcionado:

• De forma predeterminada, la imagen está etiquetada como google-workspace-mcp:local .
• Para utilizar la salida detallada (imprimir todos los registros en la consola), agregue --verbose :
  ./scripts/build-local.sh --verbose
• Para cambiar la etiqueta de imagen de Docker:
  ./scripts/build-local.sh --tag my-custom-tag
• Los archivos de registro se escriben en /tmp/google-workspace-mcp/ para su revisión.

El script de compilación utiliza Dockerfile.local , optimizado para el desarrollo local sin configuraciones específicas de la plataforma ni funciones de BuildKit. Esto garantiza la compatibilidad entre diferentes entornos de desarrollo.

Compilación manual de Docker

También puedes crear y ejecutar el contenedor manualmente:

Características

• Manejo simplificado de archivos adjuntos con gestión automática de metadatos
• Respuestas de correo electrónico optimizadas centradas en información esencial
• Sistema robusto de indexación y recuperación de archivos adjuntos
• Gestión eficiente de archivos en Gmail y Calendario
• Limpieza automática de archivos adjuntos caducados

Herramientas disponibles

Gestión de cuentas

• list_workspace_accounts (alias: lista_cuentas, obtener_cuentas, mostrar_cuentas)
  • Enumere todas las cuentas de Google configuradas y el estado de autenticación
  • Debe llamarse primero antes de otras operaciones
  • Valida los alcances de API requeridos
  • Maneja la selección de múltiples cuentas
• authenticate_workspace_account (alias: auth_cuenta, agregar_cuenta, conectar_cuenta)
  • Agregar y autenticar cuentas de Google para acceder a la API
  • Admite la categorización de cuentas (trabajo, personal)
  • Maneja el flujo OAuth con la interacción del usuario
  • Gestiona la actualización del token automáticamente
• remove_workspace_account (alias: eliminar_cuenta, desconectar_cuenta, eliminar_cuenta)
  • Eliminar cuentas de Google y tokens asociados
  • Limpiar las credenciales almacenadas

Operaciones de Gmail

Mensajes y búsqueda

• search_workspace_emails (alias: buscar_emails, encontrar_emails, consultar_emails)
  • Capacidades avanzadas de filtrado de correo electrónico:
    • Filtrado de remitente/destinatario
    • Búsqueda de tema y contenido
    • Filtrado de rango de fechas
    • Presencia de apego
    • Filtrado basado en etiquetas
    • Compatibilidad con sintaxis de consulta compleja de Gmail
  • Patrones de búsqueda comunes para:
    • Correos electrónicos de reuniones
    • Comunicaciones de RR.HH./Administración
    • Actualizaciones del equipo
    • Boletines informativos
• send_workspace_email (alias: send_email, send_mail, create_email)
  • Enviar correos electrónicos con formato completo
  • Soporte para destinatarios CC/CCO
  • Manejo de archivos adjuntos
  • Soporte para hilos de correo electrónico

Ajustes y configuración

• get_workspace_gmail_settings (alias: obtener_configuración_de_gmail, configuración_de_gmail, obtener_configuración_de_correo)
  • Acceder a la configuración de la cuenta
  • Preferencias de idioma
  • Configuración de firma
  • Estado de respuesta de vacaciones
  • Reglas de filtrado y reenvío

Gestión de borradores

• manage_workspace_draft (alias: administrar_borrador, operación_borrador, manejar_borrador)
  • Borrador completo de operaciones CRUD:
    • Crear nuevos borradores
    • Leer borradores existentes
    • Actualizar el contenido del borrador
    • Eliminar borradores
    • Enviar borradores
  • Soporte para:
    • Nuevos borradores de correo electrónico
    • Responder borradores con hilos
    • Modificaciones del borrador
    • Envío de borrador

Gestión de etiquetas

• manage_workspace_label (alias: manage_label, label_operation, handle_label)
  • Operaciones CRUD de etiqueta completa
  • Soporte para etiquetas anidadas
  • Configuración de color personalizada
  • Configuración de visibilidad
• manage_workspace_label_assignment (alias: asignar_etiqueta, modificar_etiquetas_de_mensaje, cambiar_etiquetas_de_mensaje)
  • Aplicar o quitar etiquetas de los mensajes
  • Modificaciones de etiquetas de lotes
  • Actualizaciones de etiquetas del sistema
• manage_workspace_label_filter (alias: administrar_filtro, manejar_filtro, operación_de_filtro)
  • Crear y administrar filtros de etiquetas
  • Criterios de filtrado complejos:
    • Patrones de remitente/destinatario
    • Coincidencia de tema/contenido
    • Presencia de apego
    • Reglas de tamaño de los mensajes
  • Acciones automatizadas:
    • Aplicación de etiquetas
    • Marcado de importancia
    • Estado de lectura
    • Archivado

Operaciones del calendario

Gestión de eventos

• list_workspace_calendar_events (alias: lista_eventos, obtener_eventos, mostrar_eventos)
  • Lista de eventos del calendario con filtrado
  • Especificación del rango de fechas
  • Búsqueda de texto dentro de eventos
  • Límites de resultados personalizables
• get_workspace_calendar_event (alias: obtener_evento, ver_evento, mostrar_evento)
  • Información detallada del evento
  • Estado del asistente
  • Configuración de eventos
• manage_workspace_calendar_event (alias: administrar_evento, actualizar_evento, responder_al_evento)
  • Gestión de respuesta a eventos:
    • Aceptar/Rechazar invitaciones
    • Marcar como tentativo
    • Proponer nuevos tiempos
    • Actualizar horarios de eventos
  • Soporte de comentarios
  • Manejo de zonas horarias
• create_workspace_calendar_event (alias: crear_evento, nuevo_evento, programar_evento)
  • Crear nuevos eventos de calendario
  • Soporte para:
    • Eventos individuales
    • Eventos recurrentes (formato RRULE)
    • Varios asistentes
    • Especificación de zona horaria
    • Descripción del evento
    • Comprobación de conflictos
• delete_workspace_calendar_event (alias: eliminar_evento, eliminar_evento, cancelar_evento)
  • Eliminar eventos del calendario
  • Opciones de notificación para los asistentes

Contactos Operaciones

• get_workspace_contacts (alias: obtener_contactos, listar_contactos, obtener_contactos)
  • Recuperar contactos de una cuenta de Google
  • Soporte para:
    • Información básica de contacto (nombres, correos electrónicos, teléfonos)
    • Datos de contacto ampliados
    • Paginación para listas de contactos grandes
  • Casos de uso comunes:
    • Búsqueda de contactos
    • Gestión de la libreta de direcciones
    • Recuperación de información de contacto

Operaciones de conducción

Gestión de archivos

• list_drive_files (alias: list_files, get_files, show_files)
  • Lista de archivos con filtrado opcional
  • Filtrar por carpeta
  • Soporte de consultas personalizadas
  • Ordenación y paginación
  • Selección de campo
• search_drive_files (alias: archivos_de_búsqueda, archivos_de_encuentro, archivos_de_consulta)
  • Búsqueda de texto completo en el contenido del archivo
  • Filtrar por tipo MIME
  • Filtrar por carpeta
  • Incluir/excluir archivos eliminados
  • Opciones de consulta avanzadas
• upload_drive_file (alias: upload_file, create_file, add_file)
  • Subir nuevos archivos
  • Establecer metadatos de archivo
  • Especificar carpetas principales
  • Compatibilidad con varios tipos de archivos
• download_drive_file (alias: archivo_de_descarga, obtener_contenido_del_archivo, obtener_archivo)
  • Descargar cualquier tipo de archivo
  • Exportar archivos de Google Workspace
  • Opciones de conversión de formato
  • Manejo automático de tipos MIME
• delete_drive_file (alias: eliminar_archivo, eliminar_archivo, archivo_basura)
  • Eliminar archivos y carpetas
  • Eliminación limpia de Drive

Operaciones de carpeta

• create_drive_folder (alias: crear_carpeta, nueva_carpeta, agregar_carpeta)
  • Crear nuevas carpetas
  • Compatibilidad con carpetas anidadas
  • Especificación de la carpeta principal
  • Metadatos de carpeta

Permisos

• update_drive_permissions (alias: compartir_archivo, actualizar_compartir, modificar_permisos)
  • Actualizar la configuración para compartir
  • Múltiples tipos de permisos:
    • Permisos de usuario
    • Permisos de grupo
    • Compartir dominio
    • Acceso público
  • Varios roles de acceso:
    • Dueño
    • Organizador
    • Organizador de archivos
    • Escritor
    • Comentarista
    • Lector
  • Configuración de descubrimiento para archivos públicos

Consulte la documentación de la API para obtener un uso detallado.

Muy pronto

Servicios futuros

• Compatibilidad con el SDK de administración
• Servicios adicionales de Google

Estrategia de prueba

Enfoque de pruebas unitarias

1. Burla simplificada
   • Utilice respuestas simuladas estáticas para realizar pruebas predecibles
   • Evite simulaciones complejas de extremo a extremo en pruebas unitarias
   • Concéntrese en probar una pieza de funcionalidad a la vez
   • Simular dependencias externas (OAuth, sistema de archivos) con implementaciones simples
2. Organización de pruebas
   • Pruebas de grupo por funcionalidad (por ejemplo, operaciones de cuenta, operaciones de archivo)
   • Utilice nombres de prueba claros y descriptivos
   • Mantenga las pruebas enfocadas y aisladas
   • Restablecer simulacros y módulos entre pruebas
3. Gestión simulada
   • Utilice jest.resetModules() para garantizar un estado limpio
   • Volver a requerir módulos después de cambios simulados
   • Realizar un seguimiento explícito de las llamadas a funciones simuladas
   • Verificar tanto las llamadas de función como los resultados
4. Prueba del sistema de archivos
   • Utilice estructuras JSON simples
   • Centrarse en la exactitud de los datos antes que en el formato
   • Pruebe escenarios de error (archivos faltantes, JSON no válido)
   • Verificar operaciones de archivos sin detalles de implementación
5. Manejo de tokens
   • Validación de token simulada con respuestas estáticas
   • Pruebe los escenarios de éxito y fracaso por separado
   • Verificar operaciones de token sin complejidad OAuth
   • Centrarse en la lógica de manejo de tokens del administrador de cuentas

Ejecución de pruebas

Mejores prácticas

1. Autenticación
   • Almacenar credenciales de forma segura en la configuración de MCP
   • Utilice los alcances mínimos requeridos
   • Manejar la actualización del token correctamente
2. Manejo de errores
   • Comprobar el estado de la respuesta
   • Manejar los errores de autenticación apropiadamente
   • Implementar reintentos adecuados
3. Configuración y seguridad
   • Cada usuario mantiene su propio proyecto de Google Cloud
   • Configurar las credenciales de OAuth en la configuración de MCP
   • Almacenamiento seguro de tokens en ~/.mcp/google-workspace-mcp
   • Rotación regular de tokens
   • Nunca envíes archivos confidenciales a git
   • Utilice los permisos de archivo adecuados para el directorio de configuración
4. Configuración de desarrollo local
   • Configurar las credenciales de OAuth en la configuración de MCP
   • Crear el directorio ~/.mcp/google-workspace-mcp
   • Mantenga los tokens sensibles fuera del control de versiones
   • Ejecutar script de autenticación para cada cuenta

Solución de problemas

Problemas comunes de configuración

1. Configuración faltante
   • Error: "Se requiere la variable de entorno GOOGLE_CLIENT_ID"
   • Solución: configure las credenciales de OAuth en su archivo de configuración de MCP (consulte docs/API.md para obtener más detalles)
2. Errores de autenticación
   • Error: "Credenciales OAuth no válidas"
   • Solución:
     • Verifique que su proyecto de Google Cloud esté configurado correctamente
     • Asegúrate de haberte agregado como usuario de prueba en la pantalla de consentimiento de OAuth
     • Comprueba que tanto la API de Gmail como la API de Google Calendar estén habilitadas
     • Verifique que las credenciales en la configuración de MCP coincidan con la configuración de su cliente OAuth
3. Problemas con tokens
   • Error: "Error al actualizar el token"
   • Solución: elimine la cuenta usando remove_workspace_account y vuelva a autenticarse
   • Comprueba que tu proyecto de Google Cloud tenga habilitados los ámbitos de API necesarios
4. Estructura del directorio
   • Error: "Directorio no encontrado"
   • Solución: asegúrese de que ~/.mcp/google-workspace-mcp exista con los permisos adecuados
   • Verifique que Docker tenga acceso para montar el directorio de configuración

Para obtener ayuda adicional, consulte la documentación de Manejo de errores .

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles