Google Workspace

Interactúa con servicios de Google Workspace como Gmail y Google Calendar.

Documentación

Servidor MCP de Google Workspace

Un servidor de Protocolo de Contexto de Modelo para servicios de Google Workspace. Este servidor proporciona herramientas para interactuar con Gmail y Google Calendar a través del protocolo MCP.

Características

Soporte para Múltiples Cuentas de Google
- Usar y cambiar entre múltiples cuentas de Google
- Cada cuenta puede tener metadatos y descripciones personalizados
Integración con Gmail
- Consultar correos electrónicos con búsqueda avanzada
- Leer contenido completo de correos y archivos adjuntos
- Crear y gestionar borradores
- Responder a correos electrónicos
- Archivar correos electrónicos
- Manejar archivos adjuntos
- Soporte para operaciones masivas
Integración con Calendar
- Listar calendarios disponibles
- Ver eventos del calendario
- Crear nuevos eventos
- Eliminar eventos
- Soporte para múltiples calendarios
- Soporte de zona horaria personalizada

Ejemplos de Prompts

Prueba estos ejemplos de prompts con tu asistente de IA:

Gmail

"Recupera mis últimos mensajes no leídos"
"Busca mis correos del Scrum Master"
"Recupera todos los correos de contabilidad"
"Toma el correo sobre ABC y resúmelo"
"Escribe una respuesta amable al último correo de Alice y sube un borrador"
"Responde al correo de Bob con una nota de agradecimiento. Guárdalo como borrador"

Calendar

"¿Qué tengo en mi agenda para mañana?"
"Revisa la agenda familiar de mi cuenta privada para la próxima semana"
"Necesito planificar un evento con Tim para 2 horas la próxima semana. Sugiere algunos horarios"

Requisitos Previos

Node.js >= 20
Un proyecto de Google Cloud con las APIs de Gmail y Calendar habilitadas
Credenciales OAuth 2.0 para las APIs de Google

Instalación

Clona el repositorio:

git clone https://github.com/j3k0/mcp-google-workspace.git
cd mcp-google-workspace

Instala las dependencias:
```
npm install
```
Compila el código TypeScript:
```
npm run build
```

Configuración

Configuración de OAuth 2.0

Las APIs de Google Workspace (G Suite) requieren autorización OAuth2. Sigue estos pasos para configurar la autenticación:

Crea Credenciales OAuth2:
- Ve a la Consola de Google Cloud
- Crea un nuevo proyecto o selecciona uno existente
- Habilita la API de Gmail y la API de Google Calendar para tu proyecto
- Ve a "Credenciales" → "Crear credenciales" → "ID de cliente OAuth"
- Selecciona "Aplicación de escritorio" o "Aplicación web" como tipo de aplicación
- Configura la pantalla de consentimiento OAuth con la información requerida
- Agrega URIs de redirección autorizados (incluye http://localhost:4100/code para desarrollo local)

Ámbitos OAuth2 requeridos:

[
  "openid",
  "https://mail.google.com/",
  "https://www.googleapis.com/auth/gmail.settings.basic",
  "https://www.googleapis.com/auth/calendar",
  "https://www.googleapis.com/auth/userinfo.email"
]

Crea un archivo .gauth.json en la raíz del proyecto con tus credenciales de Google OAuth 2.0:

{
  "installed": {
    "client_id": "your_client_id",
    "project_id": "your_project_id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "your_client_secret",
    "redirect_uris": ["http://localhost:4100/code"]
  }
}

Crea un archivo .accounts.json para especificar qué cuentas de Google pueden usar el servidor:
```
{
  "accounts": [
    {
      "email": "your.email@gmail.com",
      "account_type": "personal",
      "extra_info": "Primary account with Family Calendar"
    }
  ]
}
```
Puedes especificar múltiples cuentas. Asegúrate de que tengan acceso en tu aplicación de Google Auth. El campo extra_info es especialmente útil, ya que puedes agregar información aquí que quieras decirle a la IA sobre la cuenta (por ejemplo, si tiene un calendario específico).

Autenticación

Una vez que .gauth.json y .accounts.json estén configurados, autentica tus cuentas:

npm run authenticate

Esto abre un navegador para cada cuenta configurada para completar el flujo de consentimiento OAuth. El script espera hasta 5 minutos por cuenta para la devolución de llamada.

# Authenticate a specific account
npm run authenticate -- user@gmail.com

# Force re-authentication (e.g. after OAuth scope changes)
npm run authenticate -- user@gmail.com --force

# Custom config paths (same flags as the server)
npm run authenticate -- --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json

Si se instala vía npm, también puedes ejecutar:

npx mcp-gmail-authenticate

Configuración de Claude Desktop

Configura Claude Desktop para usar el servidor mcp-google-workspace:

En MacOS: Edita ~/Library/Application\ Support/Claude/claude_desktop_config.json

En Windows: Edita %APPDATA%/Claude/claude_desktop_config.json

Configuración de Servidores No Publicados

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}

Configuración de Servidores Publicados

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}

Docker

También puedes compilar y ejecutar el servidor MCP en Docker:

docker build -t mcp-google-workspace .
docker run --rm -i \
  -v "$PWD/.gauth.json:/app/.gauth.json:ro" \
  -v "$PWD/.accounts.json:/app/.accounts.json:ro" \
  -v "$PWD/.credentials:/app/.credentials" \
  -e GMAIL_ALLOW_DRAFTS=true \
  -e GMAIL_ATTACHMENTS_DIR=/app/attachments \
  mcp-google-workspace \
  node dist/server.js --credentials-dir /app/.credentials

No incluyas .gauth.json, .accounts.json, tokens OAuth o archivos .env en la imagen. El .dockerignore incluido excluye esos archivos; móntalos en tiempo de ejecución en su lugar.

Uso

Inicia el servidor:
```
npm start
```
Argumentos opcionales:
- --gauth-file: Ruta al archivo de credenciales OAuth2 (predeterminado: ./.gauth.json)
- --accounts-file: Ruta al archivo de configuración de cuentas (predeterminado: ./.accounts.json)
- --credentials-dir: Directorio para almacenar credenciales OAuth (predeterminado: directorio actual)
El servidor se iniciará y escuchará comandos MCP a través de stdin/stdout.
En la primera ejecución para cada cuenta, hará lo siguiente:
- Abrirá una ventana del navegador para la autenticación OAuth2
- Escuchará en el puerto 4100 para la devolución de llamada OAuth2
- Almacenará las credenciales para uso futuro en un archivo llamado .oauth2.{email}.json

Variables de Entorno

GMAIL_ALLOW_SENDING — configúralo en true para permitir que gmail_send envíe correos realmente. Predeterminado: deshabilitado.
GMAIL_ALLOW_DRAFTS — configúralo en true para permitir herramientas de creación de borradores. Predeterminado: deshabilitado.
GMAIL_ATTACHMENTS_DIR — directorio base bajo el cual gmail_get_attachment y gmail_bulk_save_attachments pueden escribir archivos. Las rutas de archivos adjuntos proporcionadas por el llamador se tratan como relativas a este directorio; las rutas absolutas, el recorrido y los enlaces simbólicos que escapen del directorio se rechazan. Predeterminado: ~/.mcp-gsuite/attachments.

Herramientas Disponibles

Gestión de Cuentas

gmail_list_accounts / calendar_list_accounts
- Listar todas las cuentas de Google configuradas
- Ver metadatos y descripciones de cuentas
- No se requiere user_id

Herramientas de Gmail

gmail_query_emails
- Buscar correos con la sintaxis de consulta de Gmail (por ejemplo, 'is:unread', 'from:example@gmail.com', 'newer_than:2d', 'has:attachment')
- Devuelve correos en orden cronológico inverso
- Incluye metadatos y resumen de contenido
gmail_get_email
- Recuperar contenido completo del correo por ID
- Incluye cuerpo completo del mensaje e información de archivos adjuntos
gmail_bulk_get_emails
- Recuperar múltiples correos por ID en una sola solicitud
- Eficiente para procesamiento por lotes
gmail_create_draft
- Crear nuevos borradores de correo
- Soporte para destinatarios en copia (CC)
gmail_delete_draft
- Eliminar borradores de correo por draft_id
- Nota: draft_id es distinto del ID de mensaje devuelto por gmail_query_emails. Usa gmail_list_drafts para obtenerlo.
gmail_list_drafts
- Listar borradores de Gmail, opcionalmente filtrados por una consulta de búsqueda de Gmail
- Devuelve el draft_id de cada borrador (requerido para gmail_delete_draft) junto con su message_id, asunto, destinatarios y fragmento
gmail_reply
- Responder a correos existentes
- Opción para enviar inmediatamente o guardar como borrador
- Soporte para "Responder a todos" mediante CC
gmail_get_attachment
- Descargar archivos adjuntos de correos
- Guardar en disco o devolver como recurso incrustado
gmail_bulk_save_attachments
- Guardar múltiples archivos adjuntos en una sola operación
gmail_archive / gmail_bulk_archive
- Mover correos fuera de la bandeja de entrada
- Soporte para operaciones individuales o masivas

Herramientas de Calendar

calendar_list
- Listar todos los calendarios accesibles
- Incluye metadatos del calendario, roles de acceso e información de zona horaria
calendar_get_events
- Recuperar eventos en un rango de fechas
- Soporte para múltiples calendarios
- Opciones de filtro (eventos eliminados, resultados máximos)
- Personalización de zona horaria
calendar_create_event
- Crear nuevos eventos de calendario
- Soporte para asistentes y notificaciones
- Campos de ubicación y descripción
- Manejo de zona horaria
calendar_delete_event
- Eliminar eventos por ID
- Opción para notificaciones de cancelación

Desarrollo

El código fuente está en TypeScript bajo el directorio src/
La salida de compilación va al directorio dist/
Usa módulos ES para mejor modularidad
Sigue las mejores prácticas de la API de Google

Estructura del Proyecto

mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration

Comandos de Desarrollo

npm run build: Compilar código TypeScript
npm start: Iniciar el servidor
npm run dev: Iniciar en modo desarrollo con recarga automática

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Haz commit de tus cambios
Haz push a la rama
Crea una Solicitud de Extracción (Pull Request)

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles