gmail-mcp-server

Servidor MCP que expone una sola herramienta, send_email, que envía mensajes de Gmail (con archivos adjuntos opcionales) vía Gmail API. Diseñado para usarse como un servidor MCP local de stdio dentro de Claude Code.

El alcance es deliberadamente limitado: solo gmail.send (sin acceso de lectura/modificación al buzón) — privilegio mínimo para una herramienta cuyo único trabajo es enviar correo.

Esta README está escrita a partir de una configuración real de primera vez, incluidos todos los errores que surgieron por el camino. Síguela de principio a fin y no deberías toparte con ninguno.

Nota sobre PowerShell: && no funciona como separador de comandos en Windows PowerShell (eso es sintaxis de bash/cmd). Cada línea con varios comandos más abajo está escrita en líneas separadas, o usa ; si quieres una sola línea: cd C:\Users\GaneshGupta\gmail-mcp-server; python auth_setup.py

1. Google Cloud: habilita la API y crea credenciales OAuth

La interfaz de la consola de Google para esto se renombró recientemente de "pantalla de consentimiento de OAuth" a Google Auth Platform, con los ajustes repartidos en páginas separadas de la barra de navegación izquierda (Marca / Audiencia / Clientes / Acceso a datos / Centro de verificación). Los pasos siguientes usan los nombres actuales.

1. Ve a console.cloud.google.com. Crea un proyecto nuevo o reutiliza uno existente.

2. API y servicios → Biblioteca → busca "Gmail API" → Habilitar.

3. API y servicios → Pantalla de consentimiento de OAuth (esto te lleva a la nueva sección de Google Auth Platform) → rellena la página Marca:

   • Nombre de la aplicación: lo que quieras, p. ej. gmail-mcp-tool

   • Correo electrónico de asistencia al usuario: tu dirección de Gmail

   • Correo electrónico de contacto del desarrollador: tu dirección de Gmail

   • Deja los campos de logotipo/Dominio de la aplicación en blanco por ahora — volverás al Dominio de la aplicación en el paso 4 si te aparece el error de "configuración incompleta". No los rellenes especulativamente; hazlo solo si realmente ves ese error.

4. Página Audiencia (barra de navegación izquierda) → en Usuarios de prueba → + Añadir usuarios → introduce tu propia dirección de Gmail (la que enviará el correo) → Guardar.

   Si "Añadir usuarios" está bloqueado por un banner amarillo que dice "La configuración de OAuth de tu aplicación está incompleta... Visita la página Marca" — esto ocurre porque gmail.send es un ámbito sensible, que exige que los campos de Dominio de la aplicación no estén vacíos incluso para una aplicación solo de Testing. Solución:

   • Ve a Marca → Dominio de la aplicación y rellena:

     • Página de inicio de la aplicación: https://example.com

     • Enlace de política de privacidad de la aplicación: https://example.com/privacy

     • Enlace de términos de servicio de la aplicación: https://example.com/terms

   • Esto hará que aparezca un campo Dominios autorizados. Introduce solo el dominio desnudo, sin prefijo https://:

     • Correcto: example.com

     • Incorrecto (rechazado con "Dominio no válido: no debe especificar el esquema"): https://example.com

   • Guarda en Marca (deberías ver un aviso "Cambios de marca guardados").

   • Vuelve a Audiencia → Añadir usuarios e inténtalo de nuevo — esta vez funcionará.

   Estas URLs no necesitan ser reales/funcionales — Google no las verifica mientras la aplicación siga en estado Testing; solo exige que los campos estén rellenados.

5. Página Clientes (barra de navegación izquierda) → + Crear cliente:

   • Tipo de aplicación: Aplicación de escritorio

   • Nombre: lo que quieras, p. ej. gmail-mcp-desktop

   • Crear → Descargar JSON (el botón aparece justo después de crear)

6. El archivo descargado se llamará algo así como client_secret_<long-id>.apps.googleusercontent.com.json. Renómbralo exactamente a client_secret.json y muévelo a:

   C:\Users\GaneshGupta\gmail-mcp-server\credentials\client_secret.json

   El nombre exacto del archivo importa: gmail_auth.py lo busca con ese nombre y lanza FileNotFoundError si no coincide (esto es lo que más se suele hacer mal aquí).

Related MCP server: Gmail MCP Server

2. Instala las dependencias

cd C:\Users\GaneshGupta\gmail-mcp-server
pip install -r requirements.txt

3. Inicio de sesión de una sola vez

python auth_setup.py

Qué ocurre:

1. Se abre una ventana del navegador con un inicio de sesión normal de Google.

2. Llegarás a la pantalla "Google no ha verificado esta aplicación". Esto es lo esperado: es tu propio cliente OAuth, en modo Testing, solicitando un ámbito sensible. Haz clic en Continuar (interfaz anterior: Avanzado → Ir a [nombre de la aplicación] (no seguro)).

3. Concede el permiso "Enviar correo electrónico en tu nombre".

4. El navegador muestra "El flujo de autenticación se ha completado. Puedes cerrar esta ventana."

5. La terminal imprime Authorized. Token saved to ...credentials\token.json.

Si en el paso 2, en cambio, aparece Error 403: access_denied / "no ha completado el proceso de verificación de Google... solo pueden acceder los evaluadores aprobados por el desarrollador" — tu dirección de Gmail aún no está en la lista Audiencia → Usuarios de prueba. Vuelve al paso 1.4 anterior.

Haz esto una sola vez. Después, server.py solo renueva silenciosamente el token guardado — nunca vuelve a abrir un navegador por su cuenta.

4. Comprueba el token (opcional pero recomendado)

python -c "from gmail_auth import load_credentials; c = load_credentials(); print('valid:', c.valid); print('scopes:', c.scopes); print('has refresh token:', bool(c.refresh_token))"

Espera valid: True, scopes: ['https://www.googleapis.com/auth/gmail.send'], has refresh token: True.

5. Regístrate con Claude Code

claude mcp add gmail-sender --scope user -- python C:\Users\GaneshGupta\gmail-mcp-server\server.py

--scope user lo registra globalmente — a partir de entonces queda disponible en todas las sesiones de Claude Code en esta máquina, no solo en la que ejecutaste el comando. No aparecerá retroactivamente en una sesión que ya esté en marcha — los servidores MCP se cargan al inicio de la sesión, así que usa una terminal nueva / una sesión nueva de claude para verlo.

Verifica:

claude mcp list

Deberías ver gmail-sender en la lista.

6. Cómo usarlo

En cualquier sesión de Claude Code (después del registro anterior), basta con pedirlo en lenguaje natural:

Envía un correo electrónico a jane@example.com con el asunto "Following up" y el cuerpo "..." — adjunta C:\path\to\file.pdf

Claude Code llamará directamente a la herramienta send_email. No se necesita más configuración por sesión.

Referencia de la herramienta

send_email(to, subject, body, attachments=None, cc=None, bcc=None, html=False)

• to / cc / bcc: direcciones separadas por comas

• attachments: lista de rutas de archivo locales absolutas, límite combinado de 15MB (el límite de envío en bruto de Gmail es de 25MB; 15MB de archivos en bruto deja margen para la inflación de base64 + cabeceras)

• html: ponlo a true para enviar un cuerpo HTML en lugar de texto plano

• Devuelve {status, message_id, thread_id, to, subject, attachment_count}

Índice de solución de problemas

Notas

• credentials/client_secret.json y credentials/token.json están en .gitignore — nunca hagas commit de ellos.

• Para enviar desde una cuenta de Gmail distinta, elimina credentials/token.json y vuelve a ejecutar auth_setup.py.