mcp-google-gmail

Gmail MCP

Inglés | Русский

A1 Gmail MCP permite que una aplicación de IA trabaje con tu buzón de Gmail en lenguaje natural. Busca y lee correos, prepara respuestas como borradores, envíalos cuando estés listo, mantén las etiquetas ordenadas y usa la papelera en lugar de la eliminación permanente.

Utiliza la API de Gmail con tu cuenta de Google. Distingue un borrador que aún puedes editar de un correo enviado que no se puede recuperar, y hace explícitos los límites de la API de Gmail en lugar de dar a entender que cada tarea de correo es reversible.

• 24 herramientas. Busca y lee mensajes e hilos, envía correos directamente o mediante borradores, gestiona el ciclo de vida de los borradores, las etiquetas y la papelera.
• Se conecta desde la conversación. Di "conectar Gmail": el servidor te guía a través del cliente OAuth, captura la redirección de Google en 127.0.0.1 con PKCE y guarda los tokens él mismo — sin archivos de configuración, sin reinicios.
• Envía de forma deliberada. La ruta borrador → revisión → envío es de primera clase; el envío está marcado como destructivo, y el servidor nunca reenvía después de un fallo ambiguo — un correo no se puede desenviar.
• La papelera es la red de seguridad. Eliminar correos pasa por la papelera reversible (unos 30 días); deliberadamente no existe una herramienta de eliminación permanente de mensajes.
• Lectura limitada. Los cuerpos decodificados se truncan en un límite explícito y los adjuntos vuelven como metadatos, para que un boletín largo no inunde silenciosamente la conversación.
• Alcance mínimo de Google. Utiliza solo gmail.modify — sin eliminación permanente y sin acceso a la configuración de Gmail.

Comienza con una pregunta de solo lectura:

Muestra mis correos no leídos de la última semana y dime cuáles necesitan respuesta.

Conectar el servidor · Explorar casos de uso · Abrir documentación técnica

Véalo funcionar en un minuto

Tú: ¿Qué hay sin leer en mi bandeja de entrada de esta semana sobre el contrato de Acme?

Asistente: Busca con la sintaxis de consulta de Gmail y muestra remitentes, asuntos, fechas y fragmentos. Nada cambia.

Tú: Redacta una respuesta al más reciente: enviamos la copia firmada el viernes.

Asistente: Crea un borrador en el mismo hilo y lo muestra para revisión. No se envía nada.

Tú: Envíalo.

Asistente: Envía el borrador. El envío es un paso separado y explícitamente destructivo, por lo que tu aplicación de IA puede pedir confirmación primero.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Cómo cambia el correo
• Qué puede cambiar
• Obtener acceso
• Configuración
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Necesitas Node.js 20+ y una cuenta de Google. No se requieren credenciales al instalar — el servidor se conecta desde la conversación.

1. Añade el servidor a tu aplicación de IA.
2. Di "conectar Gmail": el asistente te guía para crear el cliente OAuth y aprobar el acceso sin editar archivos de configuración.
3. Haz la pregunta de solo lectura anterior.

codex mcp add google-gmail \
  -- npx -y mcp-google-gmail@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-gmail \
  -- npx -y mcp-google-gmail@latest

claude mcp list

{
  "mcpServers": {
    "google-gmail": {
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

{
  "servers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gmail@latest"]
    }
  }
}

Qué puedes pedirle que haga

Clasificar la bandeja de entrada

• Muestra los mensajes no leídos de los últimos siete días y agrupa por remitente.
• Encuentra la conversación con Acme sobre el contrato y resúmela, de más antiguo a más reciente.
• ¿Qué mensajes tienen adjuntos esperándome? Muestra asuntos y nombres de archivo.

Escribir y enviar correo

• Redacta una respuesta en este hilo diciendo que la copia firmada sale el viernes.
• Muéstrame el borrador, ajusta la redacción y luego envíalo.
• Envía un correo breve de estado al equipo, con el gerente en copia.

Mantener el buzón organizado

• Crea una etiqueta Receipts/2026 y aplícala a los mensajes que coincidan.
• Marca los boletines de esta semana como leídos y archívalos.
• Mueve ese hilo a la papelera — y restáuralo si cambio de opinión.

Cómo cambia el correo

1. La ruta segura para enviar es un borrador: create_draft prepara el correo, get_draft lo muestra para revisión, send_draft lo envía. send_message omite el borrador y envía inmediatamente.
2. Un correo enviado es externamente irreversible. Después de un tiempo de espera o un error 5xx, el servidor no reenvía; busca in:sent antes de intentarlo de nuevo, porque un envío repetido sería un correo duplicado.
3. Eliminar un mensaje o hilo significa enviarlo a la papelera. manage_trash es reversible durante unos 30 días; deliberadamente no existe una herramienta de eliminación permanente.
4. Los borradores son la excepción: update_draft reemplaza todo el borrador (la API no tiene edición parcial) y delete_draft es permanente, porque los borradores omiten la papelera.

Cada llamada funciona en un solo buzón — la cuenta que otorgó el token. Los cuerpos decodificados se truncan en un límite configurable con indicadores explícitos, y los adjuntos vuelven solo como metadatos; el contenido de los adjuntos se obtiene mediante raw_request deliberadamente.

Qué puede cambiar

El cliente de IA controla los avisos de confirmación. El servidor marca lecturas, escrituras y herramientas destructivas para que el cliente pueda distinguir una inspección de un cambio en vivo.

Obtener acceso

Google Gmail requiere OAuth 2.0; una clave de API no es suficiente. Hay dos formas de entrar, y la primera no necesita archivos de configuración.

Conectar desde el chat (recomendado)

Di "conectar Gmail" y el asistente ejecuta el flujo contigo:

1. setup_instructions imprime la lista de verificación: crea o selecciona un proyecto de Google Cloud, habilita la API de Gmail, configura la pantalla de consentimiento y crea un cliente OAuth de Aplicación de escritorio.
2. Descarga el JSON de ese cliente ("Descargar JSON") y dale al asistente su ruta — set_client lo almacena solo para el propietario. El secreto nunca pasa por la conversación.
3. start_login devuelve un enlace de consentimiento de Google. Ábrelo en esta máquina y aprueba; el código vuelve a un listener de un solo uso en 127.0.0.1 (PKCE), nunca a través del chat.
4. finish_login intercambia el código y guarda los tokens en ~/.config/mcp-google-gmail/credentials.json (modo 0600) y los verifica con una llamada real a la API de Gmail — así, una API que aún está desactivada se detecta en ese momento.

Los tokens se releen en cada llamada, por lo que la conexión funciona de inmediato — sin reiniciar la aplicación de IA. auth_status muestra qué está conectado, logout revoca y elimina.

Variables de entorno (CI, instalaciones desatendidas)

1. Crea o selecciona un proyecto de Google Cloud y habilita la API de Gmail.

2. Configura la pantalla de consentimiento OAuth y crea un cliente OAuth de Aplicación de escritorio.

3. Autoriza la cuenta de Google cuyo buzón quieres conectar — cada llamada funciona en ese único buzón. El Playground de OAuth 2.0 puede obtener el token de actualización cuando Usar tus propias credenciales OAuth está habilitado.

4. Solicita el alcance:

   https://www.googleapis.com/auth/gmail.modify
   

   Cubre búsqueda, lectura, envío, borradores, etiquetas y la papelera — pero no la eliminación permanente ni la configuración de Gmail. La eliminación permanente mediante raw_request requiere además el alcance completo https://mail.google.com/.

Los tokens de actualización OAuth en modo de prueba pueden expirar después de siete días. Publica la aplicación OAuth, o usa una aplicación Interna en un dominio de Workspace, cuando necesites acceso de larga duración. Trata el secreto del cliente y el token de actualización como contraseñas.

Configuración

Cada variable es opcional — sin ninguna de ellas, el servidor se conecta desde el chat.

* Proporciona el trío OAuth o un token de acceso.

Datos, límites y trabajo en segundo plano

• Las solicitudes van a Gmail. El servidor local actualiza los tokens OAuth de Google y llama a la API de Gmail. Su telemetría anónima contiene un ID de instalación, versión del paquete, cliente de IA y versiones de plataforma, y nombres de herramientas — nunca tokens OAuth, contenido de correo, argumentos de herramientas o avisos. Establece ASKADS_TELEMETRY=0 para optar por no participar.
• Google mide unidades de cuota. Gmail permite aproximadamente 250 unidades de cuota por segundo por usuario; un envío cuesta 100 unidades, una lectura típica 5. Las cuentas de consumidor pueden enviar unos 500 correos al día, las cuentas de Workspace unos 2,000. En 429, el servidor usa retroceso; las lecturas también reintentan después de errores de red y 5xx, mientras que los envíos y otras escrituras nunca se reproducen después de un fallo incierto.
• No hay sondeo en segundo plano. El servidor solo se ejecuta cuando se le llama. Si tu aplicación de IA admite tareas programadas, puede revisar la bandeja de entrada periódicamente; raw_request también puede acceder a history.list para sincronización incremental.

Documentación técnica

• Catálogo de capacidades de MCP — páginas orientadas a tareas para cada herramienta.
• Todas las herramientas y entradas
• Documentación de desarrollo
• Documentación de publicación
• Referencia de la API de Gmail

Soporte

¿Encontraste un error o necesitas un escenario? Crea un issue o escribe en Telegram.

¡Llegaste al final!