Servidor MCP de Gmail

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona acceso de solo lectura a Gmail. Permite a Claude Code buscar, leer y analizar de forma segura tu bandeja de entrada de Gmail.

Características

• search_emails - Buscar usando la sintaxis de consulta de Gmail

• list_unread - Listar correos no leídos

• get_message - Obtener el contenido completo del mensaje con metadatos de archivos adjuntos

• get_thread - Obtener todos los mensajes en un hilo de conversación

• draft_reply - Preparar el contenido de un borrador de respuesta (NO lo envía)

Related MCP server: Gmail MCP Server

Requisitos previos

• Node.js 18+

• Un proyecto de Google Cloud con la API de Gmail habilitada

• Credenciales de aplicación de escritorio OAuth 2.0

Configuración de Google Cloud

1. Crear un proyecto de Google Cloud

1. Ve a Google Cloud Console

2. Haz clic en "Select a project" → "New Project"

3. Ponle nombre a tu proyecto (p. ej., "Gmail MCP Server")

4. Haz clic en "Create"

2. Habilitar la API de Gmail

1. En tu proyecto, ve a "APIs & Services" → "Library"

2. Busca "Gmail API"

3. Haz clic en ella y presiona "Enable"

3. Configurar la pantalla de consentimiento de OAuth

1. Ve a "APIs & Services" → "OAuth consent screen"

2. Selecciona "External" (o "Internal" si usas Google Workspace)

3. Rellena los campos obligatorios:

   • App name: "Gmail MCP Server"

   • User support email: tu correo electrónico

   • Developer contact: tu correo electrónico

4. Haz clic en "Save and Continue"

5. Añade los alcances (scopes):

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

6. Añade tu correo electrónico como usuario de prueba (si es externo)

7. Completa la configuración

4. Crear credenciales de OAuth

1. Ve a "APIs & Services" → "Credentials"

2. Haz clic en "Create Credentials" → "OAuth client ID"

3. Selecciona "Desktop app" como tipo de aplicación

4. Ponle nombre (p. ej., "Gmail MCP Desktop")

5. Haz clic en "Create"

6. Descarga o copia el Client ID y el Client Secret

Instalación

# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuración

1. Copia el archivo de entorno de ejemplo:

cp .env.example .env

2. Edita .env con tus credenciales de OAuth:

CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret

Primera ejecución (Autorización)

La primera vez que ejecutes el servidor, este:

1. Abrirá tu navegador para la autorización de Google

2. Te pedirá que inicies sesión y concedas permisos

3. Guardará los tokens localmente en token.json

Las ejecuciones posteriores reutilizarán los tokens guardados automáticamente.

Uso con Claude Code

Añadir el servidor MCP

claude mcp add gmail node ./dist/index.js

O añádelo manualmente a tu configuración de Claude Code:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}

Herramientas disponibles

search_emails

Busca correos electrónicos usando la sintaxis de consulta de Gmail.

Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"

list_unread

Lista los correos no leídos (atajo para la búsqueda is:unread).

get_message

Obtén el contenido completo de un correo electrónico específico mediante su ID de mensaje.

get_thread

Obtén todos los mensajes en un hilo de conversación mediante su ID de hilo.

draft_reply

Prepara un borrador de respuesta para un hilo. Proporciona contexto para redactar una respuesta pero NO envía ningún correo electrónico.

Desarrollo

# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

Notas de seguridad

• Los tokens de OAuth se almacenan localmente en token.json

• Nunca subas .env o token.json al control de versiones

• El servidor solo solicita permisos de lectura y redacción

• No se envían correos electrónicos: draft_reply solo prepara el contenido

• El contenido del correo electrónico no se registra

Solución de problemas

"Missing CLIENT_ID or CLIENT_SECRET"

Asegúrate de que tu archivo .env exista y contenga credenciales válidas.

"Authorization timeout"

El flujo de OAuth tiene un tiempo de espera de 5 minutos. Reinicia el servidor y completa la autorización rápidamente.

"Token refresh failed"

Elimina token.json y vuelve a autorizar.

"Access blocked: This app's request is invalid"

Asegúrate de que tu pantalla de consentimiento de OAuth esté configurada correctamente y que tu correo electrónico esté añadido como usuario de prueba.