multi-gmail-cowork-mcp

Un pequeño servidor MCP autohospedado que permite a un único conector personalizado de Claude buscar, leer, redactar y enviar correos a través de múltiples cuentas de Gmail autenticadas de forma independiente. Está diseñado para que cualquiera pueda desplegarlo en su propio proyecto de Google Cloud, con cero infraestructura compartida y cero cambios de código necesarios para cada despliegue.

Claude Cowork
      |
      v
Your private Multi-Gmail MCP  (your own Cloud Run project)
      |
      +-- Gmail account: "personal"
      +-- Gmail account: "work"
      +-- Gmail account: "billing"
      +-- ...more, added any time via the admin page

Pídele a Claude cosas como:

• “Busca en mi Gmail de trabajo los correos de David.”

• “Busca en todas las cuentas de Gmail conectadas la ‘factura 4831’.”

• “Lee el último correo de ACH Works, sea cual sea la cuenta que lo haya recibido.”

• “¿Cuál de mis cuentas de Gmail recibió un correo de John ayer?”

Cada resultado se atribuye explícitamente al alias de la cuenta y a la dirección de correo de la que proviene. Si pides una cuenta que no está conectada o cuya autorización ha caducado, recibes un error claro: este servidor nunca sustituye silenciosamente una cuenta por otra.

Qué no es esto

Solo Gmail. Sin Calendar, Drive, Docs, Sheets ni Contacts. Sin herramienta de borrado permanente. Sin infraestructura compartida, sin cuenta central, sin telemetría.

Related MCP server: Gmail MCP

Modelo de privacidad: quién puede ver tu correo

Google  <->  Your Google Cloud deployment  <->  Claude / Anthropic

• Tú despliegas esto en tu propio proyecto de Google Cloud, usando tu propio cliente OAuth de Google y tu propio servicio de Cloud Run.

• Google emite/puede revocar los permisos OAuth; ve tráfico OAuth normal.

• Tu despliegue es el único lugar donde se almacenan tokens de actualización de Gmail.

• Claude/Anthropic ve lo que devuelven las herramientas cuando Claude las llama (igual que cualquier otra herramienta de MCP): nada más, y nada cuando no lo estás usando.

• El autor de este repositorio no ve nunca tu correo. No existe ningún servidor compartido. El despliegue de tu primo y tu despliegue no tienen nada en común salvo el código fuente.

Lee SECURITY.md para consultar el documento completo sobre límites de confianza y justificación del diseño, incluido exactamente por qué la autenticación está implementada de esta manera y las limitaciones conocidas de este proyecto. Este README no repite ese razonamiento.

Arquitectura de un vistazo

• Lenguaje/entorno de ejecución: TypeScript sobre Node.js 20+, usando el oficial @modelcontextprotocol/sdk y la google-auth-library de Google.

• Protocolo: Streamable HTTP (el transporte remoto actualmente recomendado por MCP), sin estado: cada solicitud se maneja de forma independiente, por lo que escala bien en Cloud Run sin necesidad de afinidad de sesión.

• Autenticación Claude <-> servidor: flujo de código de autorización MCP OAuth 2.1 con PKCE/S256, Dynamic Client Registration, tokens de acceso de corta duración, tokens de actualización rotatorios y estado de autorización local al despliegue en Secret Manager.

• Autenticación servidor <-> Google: OAuth 2.0 estándar con PKCE, una concesión por cuenta de Gmail conectada, ámbito gmail.modify (leer, redactar, enviar y modificar la bandeja de entrada; sin borrado definitivo).

• Almacenamiento de cuentas: un único secreto de Google Secret Manager que contiene una pequeña matriz JSON (alias, email y token de actualización). Sin base de datos.

• Interfaz de administración: unas pocas páginas HTML sin estilo detrás de un Basic Auth HTTP, justo lo necesario para conectar o desconectar cuentas.

Requisitos previos

• Una cuenta de Google y un proyecto de Google Cloud con facturación activada (el bootstrap muestra la página exacta de facturación si no está vinculada).

• Un plan de Claude que admita conectores personalizados (para conectarse a Cowork/claude.ai).

• No se necesita nada más para el despliegue: Google Cloud Shell ya incluye gcloud, curl, openssl y jq.

Costes y facturación

Cloud Run requiere un proyecto con facturación activada. Este despliegue está pensado para uso personal o de pequeña empresa: min instances 0 (pasa automáticamente a cero cuando está inactivo) y max instances 3. En un uso normal (unas pocas búsquedas, lecturas y envíos al día) se queda dentro de las cuota Always Free de Google Cloud para Cloud Run, por lo que el coste real continuado es de $0. Eso no es una garantía: una ráfaga sostenida de solicitudes más allá de la cuota gratuita podría generar los costes normales de Cloud Run. El bootstrap muestra un enlace opcional de alerta de presupuesto para recibir una notificación antes de gastar.

Instalación de Cloud Shell en un solo comando (recomendada)

1. Abre este repositorio en Google Cloud Shell usando el botón de arriba (o usa Abrir en Cloud Shell en GitHub).

2. Si Cloud Shell lo pide, autentícate y luego ejecuta:

./scripts/bootstrap.sh

El script te pide que selecciones un proyecto (o crea uno), comprueba la facturación, activa las APIs necesarias, configura una cuenta de servicio de ejecución en Cloud Run, asigna solo los roles de Secret Manager que necesita, crea todos los secretos, despliega Cloud Run y imprime comprobaciones PASS/FAIL. Es seguro re-ejecutarlo: se conservan los secretos existentes, los registros de cuentas, las credenciales OAuth y los servicios de Cloud Run.

El script nunca imprime una contraseña, un secreto de cliente OAuth, un token de actualización, el JSON del almacén de cuentas ni un token OAuth de MCP. Los valores de los secretos se escriben como bytes exactos (sin el fallo de añadir una nueva línea al final de las credenciales). Usa ./scripts/bootstrap.sh --check para comprobación de solo lectura de los prerrequisitos en Cloud Shell.

El único paso inevitable en el navegador de Google

Google no ofrece una operación de API/CLI segura y compatible para crear un cliente OAuth web de propósito general. Cuando el bootstrap te lo pida, haz clic en la página de Google Auth Platform que imprime el script y haz lo siguiente:

• Configura la aplicación como External, añade el ámbito https://www.googleapis.com/auth/gmail.modify y añade las direcciones de Gmail que vayas a usar como usuarios de prueba.

• Crea un cliente OAuth con el tipo de aplicación Web application.

• Introduce la URI de callback exacta que imprime el script: https://<your-cloud-run-host>/oauth/google/callback.

• Pega el Client ID y el Client Secret resultantes en las instrucciones ocultas de Cloud Shell.

Si Google te del certificado una advertencia de aplicación no verificada, es lo esperado; tu uso es personal. Publica la pantalla de consentimiento como In production si quieres que los tokens de actualización sigan siendo válidos más allá del límite de siete días del modo de pruebas; no es preciso verificar la aplicación para un despliegue personal o de eso pequeño.

Al final, el bootstrap imprime la URL de administración, la URL de callback de Google, la URL de MCP y la siguiente acción que debes hacer. Claude se autentica en el endpoint MCP con su flujo OAuth compatible; no hay ninguna configuración estática que copiar o poner en una URL.

Conectar cuentas de Gmail

1. Recupera la contraseña de administrador (generado por el bootstrap, nunca se imprime) con el comando que el bootstrap te imprima al final:

   gcloud secrets versions access latest --secret=admin-password --project=YOUR_PROJECT_ID

   A continuación, abre la URL de administración impresa e inicia sesión con el nombre de usuario admin y esa contraseña.

2. Escribe un alias corto como personal o work, haz clic en Añadir cuenta de Gmail y completa la autorización de Google. La URL de autorización solicita consent select_account, así que Google muestra el selector de cuenta cada vez. La dirección mostrada después del callback es la que Google autorizó de verdad; no se toma del campo del alias.

3. Repite la operación con las cuentas de Gmail que quieras. Cada aliases es independiente y todos los resultados se atribuyen tanto al alias como a la dirección de Gmail verificada.

Conectar Claude Cowork

En Claude, ve a Ajustes → Conectores → Añadir conector personalizado y entra exactamente:

1. Nombre del conector: Multi Gmail

2. URL remota de MCP: la URL impresa que termina en /claude-mcp

3. OAuth Client ID: déjalla vacío (el servidor permite el registro dinámico de clientes)

4. OAuth Client Secret: déjalo vacío

La ruta /mcp sigue disponible para clientes existentes; usa /claude-mcp para los conectores nuevos de Claude y que su identidad de recursos OAuth sea independiente de los registros de conector antiguos.

Haz clic en Añadir y luego en Conectar. Claude descubre los metadatos de autorización MCP, se registra y abre la página Autorizar acceso de MCP del despliegue. Inicia la sesión con el nombre de usuario admin y la contraseña de administrador guardada en tu propio secreto de Secret Manager admin-password, y luego aprobar. Claude redirige a través de su callback en https://claude.ai/api/mcp/auth_callback, guarda los tokens OAuth y reconecciona. No pongas el Client ID ni el Client Secret de Gmail OAuth en Claude: esos pertenecen únicamente a la credencial de Google de Gmail.

Después de conectar el conector, pide a Claude que ejecute list_accounts, luego haz búsquedas de alias para cada cuenta y search_all_accounts para comprobar la atribución.

Verifica tu despliegue

scripts/acceptance_test.mjs demuestra que todas las funciones funcionan de extremo a extremo contra tu propio despliegue: aislamiento de cuentas, ninguna sustitínculo tras un alias erróneo, borradores y envíos con confirmación de llegada y de la identidad From. Realiza el flujo OAuth completo de MCP como un cliente remoto real y nunca imprime tokens:

MCP_BASE_URL=https://your-service.run.app \
  MCP_ADMIN_PASSWORD='...'   # Secret Manager -> admin-password
  node scripts/acceptance_test.mjs

La prueba del envío manda un correo de la cuenta-A a la cuenta-B y uno de la cuenta-B a la cuenta-A, de modo que el destinatario es siempre una cuenta tuya. Pon SKIP_SEND=1 para saltarte los envíos.

Desarrollo local (opcional)

Para iterar en el código, necesitas Node.js 20+, ejecuta npm install, copia .env.example y .env, define TOKEN_STORE=file (actualmente no hace falta) y usa npm run dev. El OAuth de Gmail en local requiere una URI de callback como http://localhost:8080/oauth/google/callback; no utilices ni revises los secretos de producción. En Windows puedes usar scripts/setup.ps1 y scripts/deploy.ps1 en lugar del bootstrap de Cloud Shell.

Reautorizar / revocar cuentas

Después de actualizarizar desde la versión anterior de solo lectura, cada cuenta existente se marca como Necesita actualización de permisos de Gmail. Ve a /admin, haz clic en Reautorizar para el mismo alias y completa el consentimiento de Google. El callback se verifica que Google realmente concedió https://www.googleapis.com/auth/gmail.modify antes de sustituir el token de actualización almacenado para ese alias. Hasta entonces, las herramientas de lectura siguen funcionando, pero el las de escritor devuelven un mensaje claro de reautorización; no se usa jamás otro alias.

Para revocar la autorización, haz clic en Desconectar al lado de la cuenta. Eso revoca el permiso en Google (hasta donde sea posible) y la elimina del almacén de credenciales al instante: a Claude se le mostrará un error claro, y nunca un uso de una cuenta alternativa, que no volverá a usarse.

Para reconectar una misma cuenta (después de haberla renovado en el lado de Google), usa Conectar cuenta con el mismo alias; solo reemplaza el registro antiguo tras una nueva autorización correcta.

Herramientas de escritura

El servidor desplegado expone create_draft y send_email. Ambas necesitan un alias explícito de cuenta donde ya te hayas conectado y nunca caen en otra cuenta distinta. send_email siempre envía desde la identidad de Gmail elegido y el resultado incluye esa dirección verificada. Las funciones de envío usan el ámbito gmail.modify, no el más amplio mail.google.com, y no hay una herramienta de borrar de manera permanente. Es recomendable que los permisos del conector de Claude permitan a las herramientas de lectura de forma automática, dejando create_draft y send_email en Requiere aprobación.

Actualizar y rotar secretos

• Actualizar el despliegue tras cambiar el código o para añadir una nueva versión de un secreto: vuelve a ejecutar ./scripts/bootstrap.sh (es idempotente; conserva cuentas, tokens y el cliente OAuth) o, en Windows, scripts/deploy.ps1. Las conexiones Gmail existentes y el conector de Claude no se ven afectados.

• Rotar la contraseña de admin: añade una nueva versión de Secret Manager para admin-password y vuelve a desplegar. Los tokens del conector de Claude siguen siendo válidos (no se derivan de la contraseña de admin); solo las aprobaciones futuras de consentimiento MCP incluirá la nueva contraseña.

• Rotar oauth-state-secret: este secreto firma todo token OAuth de MCP, así que rotarlo invalida los tokens del conector de Claude; vuelve a conectar Cl. Los tokens de estado de vinculación de Gmail en curso (vida de 10 minutos) también se invalidan; las cuentas conectadas no de Gmail no se modifican.

• Rotar una autoridad de cuenta Gmail: reconecta el mismo alias desde el panel de administración (ver Reautorizar / revocar acceso).

Cómo eliminar todo

• Elimina el acceso a Gmail: desconecta cada cuenta desde /admin, o revoca el acceso directamente en https://myaccount.google.com/permissions.

• Elimina el despliegue:

  gcloud run services delete multi-gmail-mcp --region us-central1
  gcloud secrets delete mcp-oauth-state admin-password oauth-state-secret google-client-id google-client-secret gmail-mcp-accounts
  gcloud iam service-accounts delete multi-gmail-mcp-run@YOUR_PROJECT_ID.iam.gserviceaccount.com

• Elimina el cliente OAuth: Cloud Console -> APIs & Services -> Credentials -> elimina el ID del cliente OAuth y, opcionalmente, elimina la configuración de la pantalla de consentimiento de OAuth.

• O lo más sencillo: elimina todo el proyecto de Google Cloud.

Solución de problemas

• Errores “La cuenta necesita volver a conectarse”: el token de actualización almacenado fue rechazado por Google (revocado, caducado o la pantalla de consentimiento está atascada en "Testing", ver más abajo). Vuelve a conectarlo desde /admin.

• Los tokens de actualización no dejan de caducar después de ~7 días: la pantalla de consentimiento de OAuth sigue en estado de publicación “Testing”. Publícala como “En producción” (ver el paso 3) — puede permanecer sin verificar, eso es suficiente para uso personal.

• Claude no puede acceder al conector o la conexión falla en silencio: confirma que la URL del servicio se resuelve por HTTPS puro sin redirección a otro host; luego abre la URL de MCP que termina en /claude-mcp en Claude y vuelve a hacer clic en Conectar. El servidor debe devolver los metadatos de OAuth y un desafío 401 cuando se le llama sin un token de acceso; no se requiere ninguna cabecera estática en la solicitud.

• gcloud run deploy falla con APIs no habilitadas: vuelve a ejecutar scripts/setup.ps1, o ejecuta gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com gmail.googleapis.com iam.googleapis.com.

• El desarrollo local no puede acceder a Google por HTTPS (errores de certificado): esto casi siempre es un problema de la máquina local (un proxy corporativo o antivirus que intercepta el TLS), no un error de este proyecto: comprueba los certificados raíz de confianza de tu máquina.

Google OAuth: Testing vs. uso a largo plazo

Los clientes de OAuth de Google Cloud comienzan en el estado de publicación Testing. Mientras estén en Testing , los tokens de actualización para ámbitos sensibles o restringidos (lo que incluye gmail.modify) caducan después de 7 días, sin importar cuántos usuarios tengas; esto hará que el conector falle silenciosamente cada semana si se deja tal cual.

La solución no es la verificación de Google (un proceso de varios meses diseñado para SaaS público). Es más sencillo: basta con hacer clic en Publicar aplicación para pasar la pantalla de consentimiento a En producción. Para una aplicación que solicite únicamente gmail.modify y que se mantenga en el total de cuentas de Google conectadas se mantenga por debajo de 100, la propia documentación de Google trata este caso como de uso small-scala totalmente compatible: no se requiere verificación. El único efecto visible es que cada cuenta recién conectada mostrará una advertencia de un solo clic de "Google no ha verificado esta aplicación" antes de dar el visto apropiado. Esa advertencia es normal; no significa que algo esté mal configurado. Consulta SECURITY.md para conocer las reglas y fuertes.

Estructura del repositorio

src/            TypeScript source (server, MCP tools, admin/setup UI, OAuth flows)
scripts/        bootstrap.sh (Cloud Shell), setup.ps1/deploy.ps1 (Windows),
                acceptance_test.mjs (verify any deployment end-to-end)
.env.example    Local-dev configuration template (placeholders only)
SECURITY.md     Trust model, design rationale, known limitations

Licencia

MIT — consulta LICENSE.