gmail-mcp

Gmail para tu asistente de IA: varias cuentas a la vez, en un servidor que tú controlas.

日本語版 · 简体中文

gmail-mcp conecta Gmail con Claude y cualquier otro cliente MCP. Puede buscar y leer correos, enviar y responder a todos con historial citado, reenviar, manejar adjuntos e imágenes en línea, y gestionar borradores, etiquetas e hilos, en varias cuentas de Google a la vez.

Se ejecuta como un servidor remoto en tu propio Cloudflare Worker, de modo que la misma conexión responde desde Claude Code en un portátil, claude.ai en un navegador y Claude en un teléfono. Cada conexión inicia sesión en una cuenta de Google, y el token de actualización de Google permanece en tu cuenta de Cloudflare.

Dos cosas atraen a la gente aquí. Los conectores de Gmail integrados en Claude y Google leen el correo y escriben borradores, pero no pueden enviar, y mantienen una cuenta de Google por cuenta de asistente. Los servidores que pueden enviar suelen ser procesos locales: bien en un escritorio, invisibles desde un teléfono.

Cómo se compara

google_workspace_mcp es el proyecto más completo de esta lista. Cubre todo Workspace en lugar de solo Gmail, y añade tu firma de Gmail y extrae adjuntos directamente desde una URL, cosas que gmail-mcp no hace. shinzo-labs/gmail-mcp llega a respuestas de vacaciones, delegados y S/MIME a través de sus 64 herramientas; esas viven bajo gmail.settings.*, un ámbito que gmail-mcp nunca solicita, por lo que quedan fuera de su alcance pase lo que pase con un permiso.

Dos diferencias de diseño deciden la mayor parte del resto. Enrutar cuentas mediante un argumento de llamada permite que un permiso toque todas las bandejas de entrada conectadas, mientras que vincular el buzón a la conexión significa que un argumento incorrecto no llega a nada. Y al leer, los servidores locales decodifican cada parte como UTF-8: el correo ISO-2022-JP y Shift_JIS llega distorsionado, y los mensajes largos que Gmail almacena como blobs adjuntos vuelven con un cuerpo vacío.

Related MCP server: Gmail MCP Connector

Despliégalo

Unos diez minutos. Necesitas una cuenta de Cloudflare, bun y una cuenta de Google. Un dominio en la cuenta de Cloudflare es opcional: sin él, el Worker responde en workers.dev.

1 · Crea un cliente OAuth de Google

PROJECT="gmail-mcp-$(openssl rand -hex 3)"
gcloud auth login
gcloud projects create "$PROJECT" --name="gmail-mcp"
gcloud config set project "$PROJECT"
gcloud services enable gmail.googleapis.com

Google no expone ninguna API para los dos pasos siguientes, así que se hacen en la consola de Cloud:

• Pantalla de consentimiento de OAuth → Externo y, debajo, en Público, pulsa Publicar aplicación. Si se deja en modo de pruebas, Google caduca cada token de actualización a los 7 días y cada conexión muere con su token. Publicada, la aplicación muestra una advertencia de aplicación no verificada al iniciar sesión y admite hasta 100 cuentas.

• Credenciales → Crear credenciales → ID de cliente de OAuth → Aplicación web, con https://<your-host>/callback como URI de redirecionamiento autorizado. Guarda el ID de cliente y el secreto.

<your-host> es el dominio que apuntas al Worker, o el nombre de host workers.dev que recibe en caso contrario. Desplegar primero y volver a esto para rellenarlo funciona: la guía que sirve el Worker en / muestra el valor exacto.

2 · Desplegar el Worker

El botón copia el repositorio en tu cuenta de GitHub, crea el espacio de nombres KV y el Durable Object, y solicita los cuatro secretos. Despliega en workers.dev; después podrás añadir un dominio personalizado desde Configuración → Dominios y rutas.

Desde un terminal, en su lugar:

git clone https://github.com/mkpoli/gmail-mcp && cd gmail-mcp
bun install
bun run setup

bun run setup pregunta en qué dominio responder, crea o reutiliza el espacio de nombres OAUTH_KV, toma el ID de cliente y el secreto, genera una clave para la cookie y despliega. Esas dos primeras respuestas quedan en wrangler.local.jsonc, que git ignora; wrangler.jsonc no nombra ningún espacio de nombres de una cuenta ni el dominio nadie, por lo que un clon de despliegue en cualquier destino. Reejecutar setup para rotar un único secreto no es peligroso.

3 · Conectar un cliente

Deja vacíos los campos de ID de cliente y secreto: los clientes MCP se registran solos.

claude mcp add --transport http gmail-personal https://<your-host>/mcp
claude mcp add --transport http gmail-work     https://<your-host>/mcp/work

Ejecuta /mcp en Claude Code para iniciar sesión de cada conexión en su cuenta de Google. En claude.ai, está en Configuración → Conectores → Añadir conector personalizado con la misma URL. Cualquier etiqueta de un solo segmento funciona después de /mcp/, de manera que un despliegue puede servir varias bandejas de entrada a clientes que rechazan dos servidores que comparten una URL.

Tu despliegue ofrece esta guía en https://<your-host>/.

Qué puede hacer

whoami search_messages get_message get_thread get_attachment

send_message reply_all forward_message create_draft update_draft send_draft delete_draft list_drafts stage_attachment_begin stage_attachment_append stage_attachment_finish

list_labels create_label update_label delete_label modify_labels modify_thread_labels batch_modify_messages trash_message · untrash_message trash_thread · untrash_thread

Los mensajes salen tal como los envía un cliente de correo: texto plano con una alternativa en HTML, archivos adjuntos e imágenes en línea referenciadas por cid:, anidados como multipart/mixed › multipart/related › multipart/alternative. Los asuntos y los nombres para mostrar usan la RFC 2047, y los nombres de archivo, la RFC 2231; por eso el japonés, el chino y los emojis sobreviven al viaje.

reply_all lee el campo Reply-To, From, To y Cc del original, descarta tu propia dirección y cualquier dirección desde la que envíes correo, responde desde la dirección a la que el remitente escribió, conserva la cadena References y cita el original en cualquier parte que envíes. forward_message reproduce el sobre del mensaje reenviado y puede volver a adjuntar los archivos del original.

create_draft con replyToMessageId escribe la respuesta como borrador para que puedas editarla antes de enviarla: se une al hilo del original, lleva In-Reply-To y References, deduce los destinatarios de responder a todos y el asunto Re: y cita el original. update_draft solo cambia los campos que se le den; los destinatarios ya existentes, el texto, los archivos añadidos a mano en cualquier cliente y el hilo en el que se responde se vuelven a leer y se conservan. Un archivo cuyo base64 no quepa entre los argumentos de la herramienta se prepara por partes: stage_attachment_begin devuelve una dirección de subida que acepta los bytes completos en un comando curl -T, stage_attachment_append admite el base64 por bloques, y cualquier campo attachments acepta el stagingId resultante.

La lectura está limitada a propósito: los cuerpos de los mensajes y de los hilos tienen un presupuesto de caracteres, una respuesta completa tiene un límite de bytes y un adjunto se devuelto solo en línea mientras sea lo bastante pequeño para poder leerlo. Un hilo largo de una lista de correo o un archivo grande se devuelven recortados con un aviso que lo explica, en vez de agotar el contexto del asistente.

Cómo funciona

Dos flujos OAuth se encuentran en un único Worker. El cliente MCP se autentica ante el Worker; el Worker se autentica ante Google en tu nombre. Ninguno de los dos lados tiene las credenciales del otro.

sequenceDiagram
    autonumber
    participant C as MCP client<br/>(Claude Code · claude.ai)
    participant W as Worker<br/>(OAuthProvider + McpAgent)
    participant G as Google<br/>(OAuth + Gmail API)

    C->>W: POST /register (dynamic client registration)
    C->>W: GET /authorize (PKCE challenge)
    W->>C: approval dialog
    C->>G: consent screen — pick the account
    G->>W: GET /callback?code=…
    W->>W: allowlist check on the verified email
    W->>G: exchange code → access + refresh token
    W->>C: MCP access token (Google tokens sealed inside the grant)
    C->>W: POST /mcp — tools/call
    W->>G: Gmail REST (token refreshed as needed)
    G->>W: message / thread / label data
    W->>C: tool result

Construido con

• TypeScript sobre Cloudflare Workers — los Durable Objects guardan una sesión MCP cada uno; KV guarda las autorizaciones OAuth

• Hono — enrutado de los endpoints de OAuth, la devolución de Google y la página de instalación en /

• @cloudflare/workers-oauth-provider — el servidor OAuth 2.1 contra el que se registran the clientes MCP

• antefines — McpAgent, el transporte de MCP sobre Durable Objects

• @modelcontextcontext/sdk con Zod — definiciones de herramientas y validación de argumentos

• Bun, Biome, Wrangler — instalar, probar, comprobar el lint y desplegar

Gmail se invoca en sí mismo con un fetch simple contra la API REST. El SDK oficial googleapis asume Node y trae mucho más de lo que debería llevar un Worker, así que la construcción de mensajes, el análisis de MIME y la renovación de los tokens viven en src/gmail.ts y src/utils.ts.

Puntos de enrutado

Quién puede acceder

ALLOWED_EMAILS decide; se comprueba con la dirección que Google reporta como verificada, troniendo en cuenta el permiso y antes de que exista ningún «grant»:

Cada «grant » involucra solo la bandeja que autentica, de modo que ensanchar esta lista nunca enseña acceso a las bandejas ya conectadas. Liberar * deja que desconocidos entren usarán tu despliegue y la cuota de esa Google Client para su propio correo.

Límites

Dos techos evitan que un despliegue compartido se quede sin recursos; ambos se establecen en wrangler.jsonc:

En el plan Free de Workers se aplica un límite adicional: 50 solicitudes salientes por invocación. Una lectura amplia gasta una por mensaje, así que search_messages y list_drafts quieren maxResults en 45 o menos allí; por encima de eso, el excedente vuelve como errores por mensaje en lugar de resultados. El plan de pago permite 1000.

Sube cualquiera de los dos y vuelve a desplegar. El limitador de tasa de Cloudflare lee su tope del binding en tiempo de compilación, así que el simple.limit de cada uno es el único lugar que lo cambia. Un despliegue de un solo usuario puede dejar ambos intactos — el uso normal del asistente queda muy por debajo de ellos.

Seguridad

El autoalojamiento mueve la cuestión de la confianza en lugar de eliminarla, así que aquí es donde está todo.

• Tus tokens siguen siendo tuyos. Los tokens de refresco están cifrados dentro de su concesión OAuth en tu namespace de KV. El Durable Object de una sesión guarda el token de acceso de una hora de vida, y el framework de agentes MCP mantiene una copia de la concesión allí mientras viva el objeto, token de refresco incluido. Ambos almacenes son tu propia cuenta de Cloudflare, cifrados en reposo. El correo nunca se almacena — pasa a través.

• Una sesión, un buzón. La sesión MCP está vinculada a la cuenta que la abrió, así que una concesión para un buzón no puede actuar sobre otro mediante un id de sesión prestado.

• Minimalismo de ámbitos. gmail.modify cubre lectura, envío, etiquetas y papelera. Excluye el borrado permanente y todo gmail.settings.*, manteniendo las reglas de reenvío automático y la exfiltración de filtros — los backdoors clásicos del buzón — fuera de lo que cualquier concesión robada podría hacer. Se solicitan dos ámbitos de solo lectura junto a él, userinfo.email y userinfo.profile: son cómo la lista de permitidos y el enlace de sesión saben qué cuenta inició sesión, y no llegan a ningún correo.

• Las cabeceras no se pueden contrabandear. Cada valor de cabecera saliente se rechaza si contiene CR, LF o NUL, así que ningún argumento puede escapar de su propio campo para añadir uno — un Bcc dentro de una línea de asunto, por ejemplo. Los tipos de medio se validan, y el historial citado se escapa en HTML. Lo que esto no hace es vigilar los argumentos en sí: bcc es un parámetro real, así que un modelo que actúe sobre una instrucción oculta en el cuerpo de un mensaje podría rellenarlo igualmente, y el aviso de aprobación de tu cliente sigue siendo el control sobre eso.

• El acceso se puede retirar. Reducir ALLOWED_EMAILS detiene nuevos inicios de sesión. El acceso de una sola cuenta se revoca en myaccount.google.com/connections. Rotar el secreto de cliente de Google invalida todas las concesiones a la vez.

El Worker descifra el correo en memoria mientras atiende una solicitud, como debe hacer cualquier relay alojado. Si eso es inaceptable para un buzón concreto, ejecuta un servidor MCP local para ese.

Cómo se probó

253 pruebas unitarias cubren la construcción de mensajes (anidamiento MIME, plegado RFC 2047, nombres de archivo RFC 2231, rechazo de CR/LF, ajuste de base64), la extracción del cuerpo en varios juegos de caracteres, la composición de respuestas y reenvíos, los flujos de token de Google, la lista de permitidos de inicio de sesión, las comprobaciones de CSRF y vinculación de estado que protegen el lado del navegador del inicio de sesión, y las propias herramientas contra un Gmail simulado — propiedad de sesión, composición de destinatarios, selección de adjuntos, y qué devuelve una lectura parcialmente fallida.

Más allá de eso, cada herramienta se ha ejecutado contra cuentas de Gmail reales, con una cuenta separada comprobando lo que llegaba:

Desarrollo

bun run dev     # wrangler dev on :8788
bun run check   # biome + tsc
bun test        # 253 unit tests
bun run assets  # regenerate the light and dark diagrams
bun run deploy

Preguntas y errores

Abre un issue.

Licencia

Copyright © 2026 mkpoli. Publicado bajo la Licencia MIT.

src/workers-oauth-utils.ts se deriva de la demo remote-mcp-github-oauth en cloudflare/ai, Copyright © 2025 Cloudflare, Inc., usada bajo la Licencia MIT. Ver THIRD-PARTY.md.