lite-google-workspace-mcp

Servidor MCP ligero para Gmail y Google Calendar. Cada cuenta de Google se ejecuta como un proceso independiente en su propio puerto.

Característica de seguridad importante: los envíos directos de Gmail requieren una lista allowed_recipients por cuenta. Si la lista falta o está vacía, todos los envíos se bloquean. La lista de permitidos se aplica solo a send_gmail_message; draft_gmail_message permanece sin restricciones para que los agentes puedan preparar borradores para revisión humana sin poder enviarlos.

Cómo funciona

Claude Code  --HTTP-->  lite-google-workspace-mcp (port 8001)  --Google API-->  account-A@gmail.com
             --HTTP-->  lite-google-workspace-mcp (port 8002)  --Google API-->  account-B@umd.edu

• Un proceso por cuenta de Google, cada uno escuchando en un puerto separado

• Tokens OAuth almacenados localmente en ~/.config/lite-google-workspace-mcp/tokens/<account>.json

• La renovación de tokens se gestiona automáticamente mediante google-auth

• 21 herramientas expuestas por cuenta: Gmail (búsqueda, lectura, envío, borrador, etiquetas, filtros) + Calendar (eventos, free/busy, OOO, tiempo de concentración)

Related MCP server: fastmcp-gsuite

Requisitos previos

1. Un proyecto de GCP con la API de Gmail y la API de Google Calendar habilitadas

2. Una credencial OAuth 2.0 (tipo de aplicación web) con URI de redirección http://localhost:8000/oauth2callback

3. Descarga el JSON de credencial y guárdalo como ~/.config/lite-google-workspace-mcp/client_secret.json

Instalación

git clone https://github.com/WhymustIhaveaname/lite-google-workspace-mcp.git
cd lite-google-workspace-mcp
uv sync

Configuración inicial

1. Configurar puertos

Crea ~/.config/lite-google-workspace-mcp/config.toml:

[accounts.myaccount]
port = 8001

[accounts.work]
port = 8002
allowed_recipients = ["boss@company.com", "team@company.com"]
allowed_body_formats = ["html"]

El nombre de la cuenta es solo una etiqueta que eliges. Se asigna a un archivo de token y a un puerto.

send_gmail_message solo entregará a direcciones explícitamente listadas en allowed_recipients (verificado contra para/cc/bcc, sin distinción de mayúsculas y minúsculas). Si allowed_recipients se omite o está vacío, todos los envíos se bloquean. Un campo de destinatario que no se pueda analizar en direcciones se trata como no permitido en lugar de omitirse, de modo que los separadores exóticos no puedan colar una dirección más allá de la verificación. Los borradores nunca se entregan, por lo que draft_gmail_message no está restringido por esta lista.

Tanto send_gmail_message como draft_gmail_message solo aceptan formatos listados en allowed_body_formats. Si la opción se omite, el valor predeterminado es ["html"], por lo que los mensajes de texto plano se bloquean. Añade "plain" explícitamente solo si esa cuenta necesita crear o enviar correo de texto plano.

Ambas opciones deben ser arrays TOML de cadenas, y allowed_body_formats solo acepta "plain" y "html". Cualquier otra cosa aborta el inicio del servidor en lugar de bloquear silenciosamente todos los mensajes.

Si un adjunto no se puede leer o decodificar, no se envía nada y no se crea ningún borrador. El error nombra el adjunto que falla para que se pueda corregir o eliminar antes de reintentar.

2. Autorizar cuentas

uv run lite-google-workspace-mcp auth myaccount

Esto imprime una URL de OAuth y abre tu navegador. Inicia sesión con la cuenta de Google que quieras enlazar, concede permisos (puedes omitir algunos ámbitos si quieres) y el token se guarda localmente.

Repite para cada cuenta.

3. Iniciar el servidor

Manual:

uv run lite-google-workspace-mcp serve --account myaccount

Con systemd (recomendado):

cp contrib/lite-google-workspace-mcp@.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now lite-google-workspace-mcp@myaccount

4. Conectar con Claude Code

claude mcp add --scope user --transport http lite-gmail-myaccount http://localhost:8001/mcp

Reautorización

Si un token caduca o quieres cambiar los ámbitos concedidos:

# Stop the service first (auth uses port 8000 which must be free)
systemctl --user stop lite-google-workspace-mcp@myaccount

# Re-authorize
uv run lite-google-workspace-mcp auth myaccount

# Restart
systemctl --user start lite-google-workspace-mcp@myaccount

Tokens que caducan cada 7 días

Si la pantalla de consentimiento de OAuth tiene un tipo de usuario externo y un estado de publicación en Prueba, Google caduca cada token de actualización 7 días después del consentimiento (esto se aplica a cualquier ámbito más allá del perfil/correo básico). El servicio entonces falla al iniciar con invalid_grant: Token has been expired or revoked, y reautorizar solo restablece el reloj de 7 días.

La solución es publicar la aplicación en producción: consola de GCP > APIs y servicios > Pantalla de consentimiento de OAuth > Publicar aplicación. Los tokens de actualización de producción no caducan con un temporizador. Con ámbitos de Gmail restringidos verás una advertencia de «aplicación no verificada» hasta la verificación, lo cual es inofensivo para uso personal o autoalojado.

Herramientas

Gmail (14 herramientas)

Calendar (7 herramientas)

Desarrollo

uv sync --extra dev
uv run pytest
uv run ruff check src/