MCP Google Workspace

Un servidor MCP completo para gestionar servicios de Google Workspace como Calendar, Contacts y Gmail mediante autenticación OAuth2.

GitHubPrueba este MCPPatrocinado

Documentación

MCP Google Workspace

El ÚNICO servidor MCP integral para Google Workspace que permite a Claude, Cursor, Windsurf y otros sistemas de IA gestionar completamente Google Calendar, Contactos y Gmail - ¡leer, crear, actualizar, eliminar y organizar en los tres servicios!

Integración completa de Google Workspace para Claude Desktop y otros agentes de IA que utilizan el Protocolo de Contexto de Modelo (MCP). Este servidor proporciona capacidades integrales de gestión para Calendar, Contactos y Gmail con autenticación OAuth2.

¿Por qué este servidor MCP?

Otros servidores MCP de calendario solo proporcionan acceso de solo lectura. Este es el único servidor MCP que brinda a sistemas de IA como Claude, Cursor y Windsurf la capacidad de:

Gestión de Calendario

  • ✅ Crear nuevos eventos de calendario
  • ✅ Actualizar eventos existentes (incluidos eventos recurrentes)
  • ✅ Eliminar eventos
  • ✅ Gestionar múltiples calendarios
  • ✅ Verificar disponibilidad en todos los calendarios

Gestión de Contactos

  • ✅ Listar y buscar contactos
  • ✅ Crear nuevos contactos con todos los detalles
  • ✅ Actualizar contactos existentes
  • ✅ Eliminar contactos
  • ✅ Gestionar detalles de contacto (correos electrónicos, teléfonos, direcciones, organizaciones)

Gestión de Gmail (¡NUEVO!)

  • ✅ Buscar y listar correos electrónicos con consultas potentes
  • ✅ Leer contenido completo de correos con archivos adjuntos
  • ✅ Enviar nuevos correos y respuestas
  • ✅ Organizar con etiquetas y carpetas
  • ✅ Actualizar estado del correo (leído/no leído, destacado, importante)
  • ✅ Crear y gestionar borradores
  • ✅ Operaciones por lotes para gestión masiva de correos

Características

Características del Calendario

  • Soporte Multi-Calendario: Listar eventos de múltiples calendarios simultáneamente
  • Gestión de Eventos: Crear, actualizar (incluidas notificaciones), eliminar y buscar eventos de calendario
  • Eventos Recurrentes: Ámbitos de modificación avanzados para eventos recurrentes (instancia única, todas las instancias o solo instancias futuras)
  • Gestión de Calendarios: Listar calendarios y sus propiedades
  • Consultas de Disponibilidad: Verificar disponibilidad en todos los calendarios

Características de Contactos

  • Búsqueda de Contactos: Buscar contactos por nombre, correo electrónico u otros criterios
  • Detalles Completos de Contacto: Gestionar nombres, correos electrónicos, números de teléfono, direcciones, organizaciones y notas
  • Operaciones por Lotes: Listar contactos con soporte de paginación
  • Selección de Campos: Elegir qué campos de contacto recuperar para respuestas optimizadas

Características de Gmail (¡NUEVO!)

  • Búsqueda Avanzada: Usar los potentes operadores de búsqueda de Gmail
  • Gestión de Correos: Leer, enviar, responder, reenviar y eliminar correos
  • Organización con Etiquetas: Crear y gestionar etiquetas/carpetas
  • Gestión de Borradores: Crear, actualizar y enviar borradores
  • Operaciones por Lotes: Actualizar múltiples correos a la vez
  • Soporte de Hilos: Manejar conversaciones de correo
  • Información de Adjuntos: Ver detalles de archivos adjuntos (nombres, tamaños, tipos)

Autenticación

  • Autenticación OAuth2: Autenticación segura con renovación automática de tokens
  • Permisos Unificados: Un único flujo de autenticación para acceso a Calendar, Contactos y Gmail

Instalación

Mediante npx (Recomendado)

npx mcp-google

Mediante npm

npm install -g mcp-google

Configuración

1. Crear Credenciales OAuth de Google

  1. Vaya a Google Cloud Console
  2. Cree un nuevo proyecto o seleccione uno existente
  3. Habilite estas API:
  4. Configure la pantalla de consentimiento OAuth:
    • Vaya a "APIs y servicios" > "Pantalla de consentimiento de OAuth"
    • Elija el tipo de usuario "Externo"
    • Complete los campos obligatorios (nombre de la aplicación, correo de soporte, etc.)
    • Agregue su correo electrónico como usuario de prueba (requerido mientras esté en modo de prueba)
  5. Cree las credenciales OAuth 2.0:
    • Vaya a "APIs y servicios" > "Credenciales"
    • Haga clic en "Crear credenciales" > "ID de cliente de OAuth"
    • Elija "Aplicación de escritorio" como tipo de aplicación
    • Asigne un nombre a su cliente OAuth (por ejemplo, "Cliente MCP de Calendario")
    • Descargue el archivo JSON de credenciales

2. Configurar Claude Desktop

Agregue esto a su archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Opción A: Variables de Entorno Directas (¡La más simple - No se necesita archivo JSON!)

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Opción B: Usar el Archivo de Credenciales de Google Descargado

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/downloaded/credentials.json"
      }
    }
  }
}

Simplemente use la ruta del archivo donde guardó el archivo JSON descargado de Google Cloud Console.

3. Autenticarse

  1. Reinicie Claude Desktop
  2. El servidor MCP abrirá una ventana del navegador para la autenticación
  3. Inicie sesión con su cuenta de Google y conceda permisos de Calendar, Contactos Y Gmail
  4. Los tokens se guardarán de forma segura para uso futuro

Nota: Si está actualizando desde una versión anterior, deberá volver a autenticarse para conceder los nuevos permisos de Gmail.

Variables de Entorno

  • GOOGLE_OAUTH_CREDENTIALS: Ruta al archivo JSON de credenciales OAuth
  • GOOGLE_CALENDAR_MCP_TOKEN_PATH: Ruta personalizada para el almacenamiento de tokens (opcional)
  • NODE_ENV: Establecer en "production" para uso en producción

Herramientas Disponibles

Herramientas de Calendario

list-calendars

Listar todos los calendarios accesibles con sus propiedades.

list-events

Listar eventos de uno o más calendarios con opciones de filtrado.

create-event

Crear un nuevo evento de calendario con soporte para:

  • Eventos únicos o recurrentes
  • Asistentes y notificaciones
  • Colores personalizados
  • Zonas horarias

update-event

Actualizar eventos existentes, incluyendo:

  • Modificación de instancias individuales de eventos recurrentes
  • Cambio de detalles del evento
  • Gestión de asistentes

delete-event

Eliminar eventos de calendarios.

search-events

Buscar eventos en todos los calendarios mediante consultas de texto.

get-freebusy

Consultar información de disponibilidad en múltiples calendarios.

list-colors

Listar los colores disponibles para eventos de calendario.

Herramientas de Contactos

list-contacts

Listar y buscar contactos con soporte de paginación.

get-contact

Obtener información detallada sobre un contacto específico.

create-contact

Crear nuevos contactos con:

  • Nombres y apodos
  • Múltiples direcciones de correo electrónico
  • Números de teléfono
  • Direcciones físicas
  • Organizaciones y títulos de trabajo
  • Notas y biografías

update-contact

Actualizar información de contactos existentes con actualizaciones específicas por campo.

delete-contact

Eliminar contactos de Google Contacts.

Herramientas de Gmail (¡NUEVO!)

list-emails

Buscar y listar correos electrónicos con potentes consultas de Gmail.

get-email

Leer el contenido completo del correo, incluidos el cuerpo y los archivos adjuntos.

send-email

Enviar nuevos correos o respuestas con soporte HTML.

update-email

Modificar propiedades del correo (etiquetas, estado de lectura, destacado, archivo).

delete-email

Mover correos a la papelera o eliminarlos permanentemente.

create-draft

Crear borradores de correo para editar más tarde.

update-draft

Editar borradores de correo existentes.

send-draft

Enviar un borrador guardado.

list-labels

Listar todas las etiquetas/carpetas de Gmail.

create-label

Crear nuevas etiquetas para organizar correos.

update-label

Modificar propiedades y colores de etiquetas.

delete-label

Eliminar etiquetas de Gmail.

batch-update-emails

Realizar operaciones masivas en múltiples correos.

Ejemplos de Uso

Ejemplos de Calendario

Verificar disponibilidad

What times am I free tomorrow between 9am and 5pm?

Crear un evento

Create a meeting called "Team Standup" tomorrow at 10am for 30 minutes

Buscar eventos

Find all events this week that mention "project review"

Actualizar eventos recurrentes

Change all future instances of my weekly team meeting to 2pm

Ejemplos de Contactos

Listar contactos

Show me all my contacts with email addresses

Crear un contacto

Create a contact for John Doe, email: john@example.com, phone: 555-1234

Buscar contactos

Find contacts who work at Google

Actualizar contacto

Update Jane Smith's phone number to 555-5678

Ejemplos de Gmail

Buscar correos

Show me all unread emails from this week

Enviar correo

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 2pm"

Organizar bandeja de entrada

Mark all newsletters as read and archive them

Gestionar etiquetas

Create a label called "Important Projects" and apply it to all emails from my manager

Operaciones por lotes

Move all emails older than 30 days to trash

Solución de Problemas

Problemas de Autenticación

  • Asegúrese de que la URI de redirección coincida exactamente: http://localhost:3000/oauth2callback
  • Verifique que tanto Calendar API como People API estén habilitadas en Google Cloud Console
  • Confirme que las credenciales OAuth sean de tipo "Aplicación de escritorio"
  • Si está actualizando desde una versión solo de calendario, vuelva a ejecutar la autenticación para conceder permisos de contactos

Expiración de Tokens

  • Los tokens se renuevan automáticamente
  • Si los problemas persisten, elimine el archivo de token y vuelva a autenticarse

Errores de Permisos

  • Asegúrese de haber concedido todos los permisos solicitados de Calendar, Contactos y Gmail
  • Verifique que la cuenta de Google tenga acceso a los recursos a los que intenta acceder
  • Asegúrese de que todas las API requeridas estén habilitadas en su proyecto de Google Cloud:
    • Google Calendar API
    • Google People API
    • Gmail API

Seguridad

  • Los tokens OAuth se almacenan con permisos restringidos (0600)
  • Los secretos de cliente nunca deben enviarse al control de versiones
  • Use variables de entorno para configuración sensible

Desarrollo

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

Equipo

Desarrollado por Boris Djordjevic y el equipo de 199 Longevity.

Construido sobre el google-calendar-mcp original de nspady.

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! Abra un issue o envíe un pull request en GitHub.

Registro de Cambios

v1.1.3

  • Se corrigió la validación de zona horaria para admitir milisegundos en marcas de tiempo ISO
  • Ahora es compatible con el formato Date.toISOString() de JavaScript (por ejemplo, 2024-01-01T00:00:00.000Z)
  • Se mejoró la expresión regular de validación de fecha y hora para manejar ambos formatos, con y sin milisegundos

v1.1.2

  • Se mejoró el flujo de autenticación con una página de destino clara e informativa
  • Los usuarios ahora ven exactamente qué permisos tendrá Claude antes de conectarse
  • Interfaz profesional que identifica claramente esto como autenticación de Google Calendar
  • Se agregó una nota de seguridad indicando que las credenciales nunca se almacenan

v1.1.1

  • Documentación mejorada para resaltar las capacidades únicas de gestión completa de calendario
  • Se agregó la sección "¿Por qué este servidor MCP?" enfatizando las funciones de crear/actualizar/eliminar
  • Se actualizó la descripción del paquete y las palabras clave para una mejor visibilidad

v1.1.0

  • Configuración simplificada: Se agregó soporte para variables de entorno directas (¡no se necesita archivo JSON!)
  • Los usuarios ahora pueden usar GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET directamente en la configuración de Claude
  • Se actualizó el README con instrucciones más claras para la configuración OAuth de aplicaciones de escritorio
  • Se eliminaron los pasos innecesarios de configuración de URI de redirección

v1.0.1

  • Se agregó lógica de reintento automático para errores de red
  • Se mejoró el manejo de errores para problemas de cierre de conexión
  • Recuperación silenciosa cuando los eventos se crean a pesar de errores de conexión

v1.0.0

  • Lanzamiento inicial con autenticación OAuth2 mejorada
  • Herramientas integrales de gestión de calendario
  • Soporte multi-calendario
  • Consultas de disponibilidad