gmail-read-mcp

Servidor MCP de Gmail de solo lectura, limitado a un único buzón. Expone dos herramientas a través de stdio:

• list_emails - lista los correos recibidos en un rango de fechas: metadatos + fragmento, del más antiguo al más reciente (máx. 500)

• read_email - lee los encabezados completos y el texto del cuerpo de un correo por su id

No incluye capacidades de escritura, envío, etiquetado ni borrado. Cada resultado incluye un enlace profundo jump_url (búsqueda rfc822msgid:) que abre el correo para cualquier persona con sesión iniciada en el buzón. El correo enviado desde el propio buzón (las respuestas del equipo) se excluye por defecto; el spam y la papelera siempre se excluyen.

Configuración de OAuth de Google

1. Crea un proyecto de Google Cloud (separado de cualquier proyecto de producción — la pantalla de consentimiento es por proyecto) y habilita la API de Gmail.

2. Configura la pantalla de consentimiento de OAuth como Interna (omite la verificación de alcance restringido para el alcance gmail.readonly).

3. Crea un cliente OAuth de tipo Aplicación de escritorio y descarga el JSON del cliente.

4. Ejecuta el flujo de consentimiento único con la sesión iniciada como el buzón de destino:

   node scripts/gmail-oauth-once.mjs <path-to-client-secret.json>

   Imprime el token de actualización y a qué buzón está vinculado.

El token de actualización no caduca, pero Google revoca los tokens de alcance de Gmail cuando cambia la contraseña de la cuenta. Si el servidor empieza a fallar con invalid_grant, vuelve a ejecutar el paso 4 y reemplaza GMAIL_REFRESH_TOKEN.

Related MCP server: Gmail MCP Server

Configuración local

cp .env.example .env
# Fill in GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN
npm install
npm start

Pruebas

npm test