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, por lo 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 correos 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 una concesión.

Dos diferencias de diseño deciden la mayor parte del resto. Enrutar cuentas mediante un argumento de llamada permite que una concesión toque todos los buzones conectados, 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

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 uno, el Worker responde en workers.dev.

1 · Crea un cliente de 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 siguientes pasos, por lo que se realizan en la consola de Cloud:

• Pantalla de consentimiento de OAuth → Externa y, en Audiencia, pulsa Publicar aplicación. Si se deja en Pruebas, Google caduca cada token de actualización a los 7 días y cada conexión muere con su token. Si se publica, 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://<tu-host>/callback como URI de redireccionamiento autorizado. Conserva el ID de cliente y el secreto.

<tu-host> es el dominio que apuntas al Worker, o el nombre de host workers.dev que recibe en caso contrario. Desplegar primero y volver después para rellenar esto funciona: la guía que el Worker sirve 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 pide los cuatro secretos. Despliega en workers.dev; un dominio personalizado se adjunta después en Settings → Domains & Routes.

Desde una 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 de cookie y despliega. Esas dos primeras respuestas van a wrangler.local.jsonc, que git ignora — wrangler.jsonc no nombra el espacio de nombres de ninguna cuenta ni el dominio de nadie, así que un clon despliega en cualquier sitio. Volver a ejecutar setup para rotar un único secreto es seguro.

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 que cada conexión inicie sesión en su cuenta de Google. En claude.ai es Settings → Connectors → Add custom connector con la misma URL. Cualquier etiqueta de un solo segmento funciona después de /mcp/, que es como un único despliegue sirve varias bandejas de entrada a clientes que rechazan dos servidores que comparten una URL.

Tu despliegue sirve esta guía en https://<tu-host>/.

Lo que 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 como los envía un cliente de correo: texto plano con una alternativa 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 RFC 2047, los nombres de archivo usan RFC 2231, así que el japonés, el chino y los emoji sobreviven al viaje.

reply_all lee el 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 que el remitente escribió, arrastra la cadena References y cita el original en las partes que envíes. forward_message reproduce el sobre reenviado y puede volver a adjuntar los archivos del original.

create_draft con replyToMessageId escribe la respuesta como borrador para editar antes de enviar: se une al hilo del original, arrastra In-Reply-To y References, deriva los destinatarios de responder a todos y el asunto Re:, y cita el original. update_draft cambia solo los campos que se le dan; los destinatarios, el texto, los archivos añadidos a mano en cualquier cliente y el hilo al que responde el borrador se leen y se conservan. Un archivo cuyo base64 no quepa en los argumentos de la herramienta se prepara en su lugar: stage_attachment_begin devuelve una URL de subida que acepta los bytes crudos en un solo curl -T, stage_attachment_append acepta base64 en fragmentos, y todo campo attachments acepta el stagingId resultante.

La lectura está acotada a propósito: los cuerpos de mensajes e hilos tienen presupuestos de caracteres, una respuesta completa tiene un techo de bytes, y un adjunto se devuelve en línea solo mientras sea lo bastante pequeño para leerse. Un hilo largo de lista de correo, o un archivo grande, vuelve recortado con una nota que lo indica en lugar de llenar 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. Ninguna de las dos partes tiene las credenciales de la otra.

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 en Cloudflare Workers — los Durable Objects mantienen una sesión MCP cada uno, KV mantiene las concesiones OAuth

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

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

• agents — McpAgent, el transporte MCP sobre Durable Objects

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

• Bun, Biome, Wrangler — instalar, probar, revisar, desplegar

Gmail en sí se llama mediante fetch simple contra la API REST. El SDK oficial googleapis asume Node y carga mucho más de lo que un Worker debería enviar, así que la construcción de mensajes, el análisis MIME y la renovación de tokens viven en src/gmail.ts y src/utils.ts en su lugar.

Endpoints

Quién puede iniciar sesión

ALLOWED_EMAILS lo decide, comprobado contra la dirección que Google informa como verificada — después del consentimiento, antes de que exista ninguna concesión.

Cada concesión alcanza solo la bandeja de entrada que la autenticó, así que ampliar esta lista nunca amplía el acceso a bandejas ya conectadas. Poner * deja que desconocidos usen tu despliegue, y la cuota de tu cliente de Google, para su propio correo.

Límites

Dos techos evitan que un despliegue compartido se agote, ambos establecidos en wrangler.jsonc:

En el plan gratuito de Workers se aplica un límite adicional: 50 solicitudes salientes por invocación. Una lectura amplia consume una por mensaje, así que search_messages y list_drafts requieren maxResults de 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 velocidad de Cloudflare lee su techo desde el 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 traslada la cuestión de la confianza en lugar de eliminarla, así que aquí es donde reside todo.

• Tus tokens siguen siendo tuyos. Los tokens de actualización están cifrados dentro de su concesión OAuth en tu namespace KV. El Durable Object de una sesión guarda el token de acceso con vigencia de una hora, y el framework de agentes MCP mantiene una copia de la concesión allí mientras viva el objeto, incluido el token de actualización. Ambos almacenes son de 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 alcances. 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 por filtros — las puertas traseras clásicas del buzón — fuera de lo que cualquier concesión robada podría hacer. Se solicitan dos alcances 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 alcanzan ningún correo.

• Las cabeceras no se pueden colar. Todo valor de cabecera saliente se rechaza si contiene CR, LF o NUL, así que ningún argumento puede salirse 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 la indicación 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 relé 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 base64), la extracción del cuerpo entre 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 CSRF y de enlace 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 deriva de la demo remote-mcp-github-oauth en cloudflare/ai, Copyright © 2025 Cloudflare, Inc., usada bajo la Licencia MIT. Consulta THIRD-PARTY.md.