hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Allows managing Gmail inbox, drafting emails, sorting newsletters, setting up labels and filters, handling attachments, and tracking responses to threads
Integrates with Google Workspace, providing access to Gmail, Calendar, and Drive within a unified interface through authenticated API access
Enables calendar management including scheduling meetings, managing recurring events, finding available time slots, and handling timezone conflicts
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.
- Crear un proyecto de Google Cloud:Copy
- Agregar a la configuración de Cline (por ejemplo,
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):Modos de registro:Copynormal(predeterminado): utiliza métodos de consola apropiados para cada nivel de registrostrict: enruta todos los mensajes que no sean JSON-RPC a stderr (recomendado para el escritorio Claude)
- Reiniciar Cline/Claude
- 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
Antes de utilizar este servidor MCP, debe configurar su propio proyecto de Google Cloud con acceso a las API de Google Workspace:
- Crear un nuevo proyecto en Google Cloud Console
- Habilite las API requeridas:
- API de Gmail
- API de Google Calendar
- API de Google Drive
- Configurar la pantalla de consentimiento de OAuth:
- Configurar como "Externo"
- Agreguese como usuario de prueba
- Agregar los ámbitos requeridos para Gmail, Calendario y Drive
- 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:
- Su ID de cliente de Google OAuth y su secreto de los pasos anteriores
- 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 servidor requiere un archivo
accounts.jsonen el directorio de configuración montado. Para la primera configuración, copieaccounts.example.jsonenaccounts.jsonen el directorio de configuración antes de iniciar el contenedor.
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:Copy - Para cambiar la etiqueta de imagen de Docker:Copy
- 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
- Capacidades avanzadas de filtrado de correo electrónico:
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
- Borrador completo de operaciones CRUD:
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: filtro_administrar, filtro_manejar, 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
- Gestión de respuesta a eventos:
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
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
- 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
- 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
- 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
- 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
- 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
- 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
- Manejo de errores
- Comprobar el estado de la respuesta
- Manejar los errores de autenticación apropiadamente
- Implementar reintentos adecuados
- 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
- 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
- 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)
- 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
- Problemas con tokens
- Error: "Error al actualizar el token"
- Solución: elimine la cuenta usando
remove_workspace_accounty vuelva a autenticarse - Comprueba que tu proyecto de Google Cloud tenga habilitados los ámbitos de API necesarios
- 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
This server cannot be installed
Proporciona acceso autenticado a las API de Google Workspace con un enfoque en las operaciones de Gmail y soporte planificado para Calendario, con autenticación OAuth segura y administración de múltiples cuentas con manejo detallado de errores.
- TL;DR Setup
- Prerequisites
- Features
- Available Tools
- Coming Soon
- Testing Strategy
- Best Practices
- Troubleshooting
- License