Gmail MCP

Servidor IMAP MCP de Gmail

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración de Gmail mediante IMAP. Este servidor permite que los asistentes de IA interactúen con las cuentas de Gmail, ofreciendo funciones para leer, buscar y gestionar correos electrónicos.

Características

Autenticación OAuth2 con Gmail
Leer correos electrónicos de cuentas de Gmail con capacidades de búsqueda avanzada
Busque correos electrónicos con filtrado completo (fechas, etiquetas, palabras clave, etc.)
Manejo especial para correos electrónicos de formularios de contacto
Ver correos electrónicos no leídos con opciones de filtrado adicionales
Enviar correos electrónicos con archivos adjuntos
Administrar etiquetas (crear, eliminar, listar)
Mover correos electrónicos entre etiquetas
Descargar archivos adjuntos
Marcar correos electrónicos como leídos/no leídos
Compatibilidad con múltiples cuentas de Gmail
Integración con asistentes de IA a través de MCP
Manejo de comillas invertidas para una mejor compatibilidad con Claude

Prerrequisitos

Antes de ejecutar el servidor IMAP MCP de Gmail, asegúrese de tener lo siguiente:

Python 3.12 o superior
Proyecto de Google Cloud con la API de Gmail habilitada
Credenciales de ID de cliente de OAuth 2.0

Instalación

Instalar desde la fuente

Clonar el repositorio:
git clone https://github.com/yourusername/gmail-imap-mcp.git cd gmail-imap-mcp
Crear y activar un entorno virtual:
python -m venv .venv # On Windows .venv\Scripts\activate # On Unix/MacOS source .venv/bin/activate
Instalar el paquete:
pip install -e .

Configurar el proyecto de Google Cloud

Vaya a la consola de Google Cloud
Crea un nuevo proyecto o selecciona uno existente
Habilite la API de Gmail para su proyecto:
- Vaya a "API y servicios" > "Biblioteca".
- Busque "API de Gmail" y habilítela
Crear credenciales OAuth 2.0:
- Vaya a "API y servicios" > "Credenciales".
- Haga clic en "Crear credenciales" > "ID de cliente OAuth".
- Seleccione "Aplicación de escritorio" como tipo de aplicación
- Descargar el archivo de configuración del cliente
Guarde el archivo descargado como client_secret.json en el directorio de credenciales:
mkdir -p ~/.gmail_imap_mcp_credentials # Move the downloaded file to ~/.gmail_imap_mcp_credentials/client_secret.json

Mejoras recientes

Funcionalidad de búsqueda mejorada

El servidor IMAP MCP de Gmail ahora cuenta con capacidades de búsqueda significativamente mejoradas:

Sintaxis de consulta al estilo de Gmail : utilice consultas al estilo de Gmail como from:example@gmail.com is:unread has:attachment
Compatibilidad con caracteres especiales : consulte etiquetas con caracteres especiales (por ejemplo, label:$$$$$ )
Filtrado de rango de fechas : busque correos electrónicos por rangos de fechas con los parámetros after_date y before_date
Filtrado combinado : combine criterios de búsqueda para un filtrado de correo electrónico preciso
Parámetros de búsqueda adicionales : filtrar por estado leído/no leído, archivos adjuntos, etc.

Procesamiento de correo electrónico del formulario de contacto

Tratamiento especial de los correos electrónicos enviados desde formularios de contacto:

Detección automatizada : identifica los correos electrónicos enviados desde los formularios de contacto del sitio web
Extracción de remitente real : extrae el remitente real de los encabezados de respuesta o líneas "De" integradas
Identificación de la fuente del sitio web : muestra de qué sitio web proviene el formulario de contacto
Extracción de mensajes limpios : extrae solo el contenido del mensaje, eliminando los metadatos del formulario
Formato de visualización mejorado : muestra los correos electrónicos del formulario de contacto en un formato claro y estructurado.

Manejo de JSON con comillas invertidas

Se agregó soporte para manejar la tendencia de Claude a usar comillas invertidas en JSON:

Conversión automática : convierte JSON con formato de comillas invertidas ( name ) en JSON adecuado ("nombre")
Manejo de errores : proporciona mensajes de error útiles sobre problemas de formato JSON
Integración perfecta : funciona automáticamente, no necesita manipulación especial

Guía de escritorio de Claude

Esta sección proporciona orientación específica para Claude Desktop al usar el servidor MCP de Gmail. Destaca las herramientas clave y las prácticas recomendadas para una gestión eficaz del correo electrónico.

Herramientas y funciones clave

1. Funciones de respuesta (CRÍTICAS)

Hay dos funciones de respuesta distintas disponibles, cada una con una finalidad específica:

responder-al-mensaje : para responder a correos electrónicos recién llegados que no tienen una comunicación previa de ida y vuelta.
responder-al-hilo : para continuar conversaciones existentes donde ya hay comunicación de ida y vuelta.

IMPORTANTE : Utilice siempre la función de respuesta adecuada:

Utilice reply-to-message para las respuestas iniciales a los mensajes nuevos
Utilice reply-to-thread para continuar conversaciones existentes
Usar send-email en su lugar romperá el hilo de correo electrónico y creará conversaciones desconectadas.

2. Recuperación de contenido de correo electrónico

get-email : utilice siempre esta herramienta para recuperar el contenido completo del correo electrónico, incluido el cuerpo, los encabezados y la información real del remitente para los formularios de contacto antes de responder.

Mejores prácticas para Claude

Obtenga siempre el contenido completo del correo electrónico : antes de responder, utilice siempre get-email para ver el mensaje completo, incluida la información real del remitente.
Usa las funciones de respuesta adecuadas : Nunca uses send-email al responder correos electrónicos existentes, ya que rompe el hilo. Usa la función de respuesta adecuada.
Manejar correctamente los formularios de contacto : para el envío de formularios de contacto, verifique la información verdadera del remitente en el contenido del correo electrónico que proviene de get-email .
Marcar correos electrónicos como leídos : marque siempre los correos electrónicos como leídos después de procesarlos para evitar respuestas duplicadas.
Gestión de hilos : utilice reply-to-thread cuando continúe conversaciones existentes para mantener una cadena de correo electrónico adecuada.

Casos especiales

Correos electrónicos del formulario de contacto

Al gestionar correos electrónicos del formulario de contacto:

Busque la información del "Remitente verdadero" proporcionada por el analizador mejorado
Responda al verdadero remitente en lugar de a la dirección de envío del formulario
Mantenga un tono profesional apropiado mientras representa a la empresa.

ID de correo electrónico y URI de recursos

Al trabajar con identificaciones de correo electrónico, puede encontrar dos formatos:

Identificadores sin procesar (por ejemplo, 12345 )
URI de recursos (por ejemplo, email://message/account_INBOX_12345 )

Se han actualizado todas las herramientas para gestionar ambos formatos correctamente.

Flujo de trabajo recomendado

Busque correos electrónicos no leídos usando get-unread-emails
Para cada correo electrónico no leído, utilice get-email para recuperar el contenido completo
Determinar si se trata de una nueva conversación o la continuación de un hilo existente
Utilice la función de respuesta adecuada ( reply-to-message o reply-to-thread )
Marcar el correo electrónico como leído usando mark-as-read

Recuerda, la función principal de Claude es responder correctamente a los correos electrónicos, no iniciar nuevas conversaciones. ¡Usa siempre la función de respuesta correcta para mantener una conversación fluida!

Referencia de herramientas

Autenticación

authenticate-gmail : Autenticar una cuenta de Gmail para usarla en MCP

Recuperación de correo electrónico

search-emails : busca correos electrónicos con filtrado avanzado
get-unread-emails : Reciba correos electrónicos no leídos con opciones de filtrado adicionales
get-email : Obtenga detalles completos de un correo electrónico específico

Envío de correo electrónico

send-email : envía un nuevo correo electrónico con archivos adjuntos opcionales
reply-to-message : Responder a un correo electrónico específico
reply-to-thread : Responder a un hilo de correo electrónico (mensaje más reciente)

Gestión de etiquetas

list-labels : Lista todas las etiquetas disponibles
create-label : Crea una nueva etiqueta
delete-label : Eliminar una etiqueta existente
move-email : Mueve correos electrónicos entre etiquetas

Organización del correo electrónico

download-attachment : Descargar archivos adjuntos de correo electrónico
mark-as-read : marcar un correo electrónico como leído
mark-as-unread : marcar un correo electrónico como no leído

Ejemplos de uso avanzado

Búsqueda mejorada con rango de fechas y etiqueta

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "$$$$$",
    "query": "important project",
    "after_date": "2023/01/01",
    "before_date": "2023/12/31",
    "is_unread": true,
    "limit": 20
  }
}

Reciba correos electrónicos no leídos con filtrado adicional

{
  "name": "get-unread-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "$$$$$",
    "additional_query": "client meeting",
    "after_date": "2023/06/01",
    "limit": 10
  }
}

Buscar con consultas complejas de Gmail

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "query": "from:client@example.com has:attachment -in:trash",
    "limit": 15
  }
}

Detalles de arquitectura e implementación

Almacenamiento de credenciales

El servidor MCP IMAP de Gmail almacena las credenciales de OAuth2 en el directorio personal del usuario, en ~/.gmail_imap_mcp_credentials/ . Este enfoque ofrece varias ventajas:

Seguridad : Las credenciales se almacenan en una ubicación específica del usuario en lugar de en el directorio de la aplicación.
Persistencia : las credenciales persisten en diferentes sesiones y reinicios de la aplicación.
Compatibilidad : evita problemas de permisos en sistemas de archivos de solo lectura

El directorio de credenciales contiene:

client_secret.json : Sus credenciales de cliente OAuth de Google Cloud Console
Archivos de token para cada cuenta de Gmail autenticada (formato: token_{email_address}.json )

Implementación de IMAP

El servidor utiliza la biblioteca imaplib2 de Python para las operaciones IMAP con Gmail. Los detalles clave de la implementación incluyen:

Conexión : Conexión segura al servidor IMAP de Gmail ( imap.gmail.com ) en el puerto 993
Autenticación : autenticación OAuth2 mediante el mecanismo XOAUTH2
Recuperación de correo electrónico : los correos electrónicos se recuperan utilizando el formato RFC822 y se analizan con el módulo email de Python
Administración de etiquetas : las etiquetas de Gmail se administran a través de las operaciones del buzón IMAP
Análisis de consultas de Gmail : las consultas de estilo Gmail se convierten de forma inteligente en criterios de búsqueda IMAP

Formato de ID de correo electrónico

Las identificaciones de correo electrónico en el sistema siguen este formato:

email://message/{account}_{mailbox}_{id}

Dónde:

{account} : La dirección de la cuenta de Gmail
{mailbox} : El buzón/etiqueta que contiene el correo electrónico
{id} : El ID IMAP único del correo electrónico

Este formato permite que el sistema identifique de forma única los correos electrónicos en diferentes cuentas y buzones de correo.

Contribuyendo

Agradecemos cualquier contribución para mejorar el servidor IMAP MCP de Gmail. No dude en enviarnos informes o solicitudes de incorporación de cambios.

Uso

Iniciando el servidor

Ejecute el servidor IMAP MCP de Gmail:

gmail-imap-mcp

Autenticación de cuentas de Gmail

Utilice la herramienta authenticate-gmail con su dirección de correo electrónico
Siga el flujo de autenticación OAuth2 en su navegador
Una vez autenticado, el servidor almacenará sus credenciales para uso futuro.

Herramientas y ejemplos disponibles

El servidor IMAP MCP de Gmail ofrece un conjunto completo de herramientas para interactuar con las cuentas de Gmail. A continuación, se muestra una lista detallada de todas las herramientas disponibles, junto con ejemplos de cómo usarlas.

Autenticación

1. autenticar-gmail

Autenticar una cuenta de Gmail para utilizarla con el servidor MCP.

Parámetros:

email : Dirección de correo electrónico para autenticarse

Ejemplo:

{
  "name": "authenticate-gmail",
  "arguments": {
    "email": "your.email@gmail.com"
  }
}

Recuperación y búsqueda de correo electrónico

2. búsqueda de correos electrónicos

Busque correos electrónicos en una cuenta de Gmail utilizando varios criterios de búsqueda.

Parámetros:

account : Cuenta de correo electrónico para buscar en
mailbox : Buzón donde buscar (predeterminado: BANDEJA DE ENTRADA)
query : Consulta de búsqueda
limit : Número máximo de correos electrónicos a devolver (predeterminado: 10)

Ejemplo: Buscar correos electrónicos de un remitente específico:

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "INBOX",
    "query": "from:sender@example.com",
    "limit": 5
  }
}

Ejemplo: Buscar correos electrónicos con un asunto específico:

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "query": "subject:\"Meeting Invitation\""
  }
}

Ejemplo: Buscar correos electrónicos con texto específico en el cuerpo:

{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "query": "TEXT \"project update\""
  }
}

3. obtener correos electrónicos no leídos

Recibir correos electrónicos no leídos de una cuenta de Gmail.

Parámetros:

account : Cuenta de correo electrónico para recibir correos electrónicos
mailbox : Buzón para recibir correos electrónicos (predeterminado: BANDEJA DE ENTRADA)
limit : Número máximo de correos electrónicos a devolver (predeterminado: 10)

Ejemplo:

{
  "name": "get-unread-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "limit": 20
  }
}

Redacción y envío de correos electrónicos

4. enviar correo electrónico

Envíe un correo electrónico desde una cuenta de Gmail con archivos adjuntos opcionales y contenido HTML.

Parámetros:

account : Cuenta de correo electrónico desde la que enviar
to : Direcciones de correo electrónico del destinatario, separadas por comas para múltiples
subject : Asunto del correo electrónico
body : Cuerpo del correo electrónico en texto sin formato
cc : Destinatarios de copia carbón (opcional)
bcc : Destinatarios con copia oculta (opcional)
html_body : versión HTML del cuerpo del correo electrónico (opcional)
attachments : Lista de objetos adjuntos (opcional)
- Cada objeto adjunto requiere:
  - path : Ruta al archivo
  - filename : nombre de archivo personalizado (opcional)
  - content_type : tipo MIME (opcional)

Ejemplo - Correo electrónico simple:

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Hello from Gmail MCP",
    "body": "This is a test email sent via the Gmail IMAP MCP server."
  }
}

Ejemplo: correo electrónico con CC, CCO y contenido HTML:

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Meeting Agenda",
    "body": "Please find the agenda for our upcoming meeting.",
    "cc": "manager@example.com",
    "bcc": "archive@example.com",
    "html_body": "<h1>Meeting Agenda</h1><p>Please find the agenda for our <b>upcoming meeting</b>.</p>"
  }
}

Ejemplo - Correo electrónico con archivo adjunto:

{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Document Attached",
    "body": "Please find the attached document.",
    "attachments": [
      {
        "path": "/path/to/document.pdf",
        "filename": "important_document.pdf",
        "content_type": "application/pdf"
      }
    ]
  }
}

5. responder al mensaje

Responder a un mensaje de correo electrónico específico con archivos adjuntos opcionales y contenido HTML.

Parámetros:

account : Cuenta de correo electrónico desde la que responder
email_id : ID de correo electrónico al que responder (formato: email://message/{account}_{mailbox}_{id} o ID sin procesar)
body : Cuerpo de respuesta en texto simple
mailbox : Buzón que contiene el correo electrónico (predeterminado: BANDEJA DE ENTRADA)
html_body : versión HTML de la respuesta (opcional)
attachments : Lista de objetos adjuntos (opcional)
- Cada objeto adjunto requiere:
  - path : Ruta al archivo
  - filename : nombre de archivo personalizado (opcional)
  - content_type : tipo MIME (opcional)

Ejemplo - Respuesta simple:

{
  "name": "reply-to-message",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "body": "Thanks for your email. I'll review your proposal and get back to you soon."
  }
}

Ejemplo - Responder con archivo adjunto:

{
  "name": "reply-to-message",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "body": "Please find my feedback attached.",
    "html_body": "<p>Please find my <b>feedback</b> attached.</p>",
    "attachments": [
      {
        "path": "/path/to/feedback.pdf",
        "filename": "project_feedback.pdf"
      }
    ]
  }
}

6. responder al hilo

Responder a un hilo de correo electrónico (utilizando el mensaje más reciente del hilo) con archivos adjuntos opcionales y contenido HTML.

Parámetros:

account : Cuenta de correo electrónico desde la que responder
thread_id : ID del hilo al que responder (formato: email://message/{account}_{mailbox}_{id} o ID sin procesar)
body : Cuerpo de respuesta en texto simple
mailbox : Buzón que contiene el hilo (predeterminado: BANDEJA DE ENTRADA)
html_body : versión HTML de la respuesta (opcional)
attachments : Lista de objetos adjuntos (opcional)
- Cada objeto adjunto requiere:
  - path : Ruta al archivo
  - filename : nombre de archivo personalizado (opcional)
  - content_type : tipo MIME (opcional)

Ejemplo - Respuesta de hilo simple:

{
  "name": "reply-to-thread",
  "arguments": {
    "account": "your.email@gmail.com",
    "thread_id": "email://message/your.email@gmail.com_INBOX_12345",
    "body": "Let's continue this discussion in our meeting tomorrow."
  }
}

Gestión de etiquetas

7. crear-etiqueta

Crear una nueva etiqueta/buzón en una cuenta de Gmail.

Parámetros:

account : Cuenta de correo electrónico para crear etiqueta en
label_name : Nombre de la etiqueta a crear

Ejemplo:

{
  "name": "create-label",
  "arguments": {
    "account": "your.email@gmail.com",
    "label_name": "ProjectX"
  }
}

8. eliminar etiqueta

Eliminar una etiqueta/buzón de una cuenta de Gmail.

Parámetros:

account : Cuenta de correo electrónico de la que se eliminará la etiqueta
label_name : Nombre de la etiqueta a eliminar

Ejemplo:

{
  "name": "delete-label",
  "arguments": {
    "account": "your.email@gmail.com",
    "label_name": "OldProject"
  }
}

9. etiquetas de lista

Enumera todas las etiquetas/buzones de correo en una cuenta de Gmail.

Parámetros:

account : Cuenta de correo electrónico para listar etiquetas desde

Ejemplo:

{
  "name": "list-labels",
  "arguments": {
    "account": "your.email@gmail.com"
  }
}

Organización del correo electrónico

10. mover correo electrónico

Mover un correo electrónico de una etiqueta/buzón a otro.

Parámetros:

account : Cuenta de correo electrónico
email_id : ID de correo electrónico para mover (formato: email://message/{account}_{mailbox}_{id} )
source_mailbox : Buzón de origen
target_mailbox : Buzón de destino

Ejemplo:

{
  "name": "move-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "source_mailbox": "INBOX",
    "target_mailbox": "ProjectX"
  }
}

Manejo de archivos adjuntos

11. archivo adjunto de descarga

Descargar un archivo adjunto de un correo electrónico.

Parámetros:

account : Cuenta de correo electrónico
email_id : ID de correo electrónico (formato: email://message/{account}_{mailbox}_{id} )
attachment_index : Índice del archivo adjunto a descargar (basado en 0)
mailbox : Buzón que contiene el correo electrónico (predeterminado: BANDEJA DE ENTRADA)
download_dir : Directorio donde guardar el archivo adjunto (predeterminado: "descargas")

Ejemplo:

{
  "name": "download-attachment",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345",
    "attachment_index": 0,
    "download_dir": "my_attachments"
  }
}

Gestión del estado del correo electrónico

12. marcar como leído

Marcar un correo electrónico como leído.

Parámetros:

account : Cuenta de correo electrónico
email_id : ID de correo electrónico (formato: email://message/{account}_{mailbox}_{id} )
mailbox : Buzón que contiene el correo electrónico (predeterminado: BANDEJA DE ENTRADA)

Ejemplo:

{
  "name": "mark-as-read",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345"
  }
}

13. marcar como no leído

Marcar un correo electrónico como no leído.

Parámetros:

account : Cuenta de correo electrónico
email_id : ID de correo electrónico (formato: email://message/{account}_{mailbox}_{id} )
mailbox : Buzón que contiene el correo electrónico (predeterminado: BANDEJA DE ENTRADA)

Ejemplo:

{
  "name": "mark-as-unread",
  "arguments": {
    "account": "your.email@gmail.com",
    "email_id": "email://message/your.email@gmail.com_INBOX_12345"
  }
}

Indicaciones disponibles

El servidor proporciona las siguientes indicaciones para que las utilicen los asistentes de IA:

1. resumir correos electrónicos

Crea un resumen de correos electrónicos recientes.

Parámetros:

account : Cuenta de correo electrónico para resumir
mailbox : Buzón para resumir (predeterminado: BANDEJA DE ENTRADA)
count : Número de correos electrónicos para resumir (predeterminado: 5)

Ejemplo:

{
  "name": "summarize-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "INBOX",
    "count": 10
  }
}

Integración con asistentes de IA

El servidor MCP IMAP de Gmail se puede integrar con asistentes de IA compatibles con el Protocolo de Contexto de Modelo (MCP). A continuación, se muestra un flujo de trabajo típico:

Autenticación : el asistente de IA utiliza la herramienta authenticate-gmail para autenticar la cuenta de Gmail del usuario.
Gestión de correo electrónico : el asistente puede recuperar, buscar y gestionar correos electrónicos utilizando las distintas herramientas proporcionadas por el servidor.
Redacción de correos electrónicos : el asistente puede ayudar a redactar y enviar correos electrónicos según las instrucciones del usuario.
Organización del correo electrónico : el asistente puede ayudar a organizar los correos electrónicos creando etiquetas, moviéndolos entre etiquetas y marcándolos como leídos o no leídos.
Resumen de correo electrónico : el asistente puede resumir correos electrónicos mediante el mensaje de summarize-emails .

Conexión con asistentes de IA

Escritorio de Claude

Para conectar el servidor IMAP MCP de Gmail con Claude Desktop:

Inicie el servidor IMAP MCP de Gmail:
python -m gmail_imap_mcp.server
Abra Claude Desktop y navegue hasta Configuración (ícono de engranaje)
Desplácese hacia abajo hasta la sección "Avanzado" y haga clic en "Editar configuración de MCP".
Agregue la configuración del servidor IMAP MCP de Gmail:
{ "servers": [ { "name": "Gmail IMAP", "url": "http://localhost:8080", "tools": [ "authenticate-gmail", "get-unread-emails", "get-email", "search-emails", "reply-to-message", "reply-to-thread", "send-email", "list-labels", "create-label", "delete-label", "move-email", "mark-as-read", "mark-as-unread", "download-attachment" ] } ] }
Haga clic en "Guardar" y reinicie Claude Desktop
Ahora puedes pedirle a Claude que interactúe con tu cuenta de Gmail. Para obtener mejores resultados, consulta la sección "Guía de escritorio de Claude" más arriba para saber cómo usar correctamente las funciones de respuesta y las prácticas recomendadas para la gestión del correo electrónico.Tareas recomendadas para probar:
- "Muéstrame mis correos electrónicos no leídos"
- Obtener el contenido completo del correo electrónico [ID]
- "Responder a este correo electrónico con [contenido]"
- Continuar este hilo de correo electrónico con [contenido]
- "Marcar este correo electrónico como leído"
- "Buscar correos electrónicos de [remitente]"

NOTA IMPORTANTE: Para las respuestas por correo electrónico, utilice siempre las funciones de respuesta adecuadas ( reply-to-message o reply-to-thread ) en lugar de send-email para mantener un hilo de correo electrónico adecuado.

IDE de windsurf

Para conectar el servidor IMAP MCP de Gmail con Windsurf IDE:

Inicie el servidor IMAP MCP de Gmail:
python -m gmail_imap_mcp.server
Abra Windsurf IDE y navegue hasta Configuración
Busque la sección "AI Flow" o "Configuración de MCP"
Agregue la configuración del servidor IMAP MCP de Gmail:
{ "servers": [ { "name": "Gmail IMAP", "url": "http://localhost:8080", "tools": [ "list-emails", "get-email", "search-emails", "send-email", "list-mailboxes", "create-label", "move-email", "mark-as-read", "download-attachment" ] } ] }
Guarde la configuración y reinicie Windsurf si es necesario
Ahora puedes pedirle a Cascade (el asistente de inteligencia artificial de Windsurf) que interactúe con tu cuenta de Gmail usando los mismos comandos que con Claude Desktop

Casos de uso comunes

1. Clasificación de correo electrónico

Assistant: I'll help you triage your unread emails.
User: Yes, please check my unread emails.
Assistant: [Uses get-unread-emails tool]
Assistant: You have 5 unread emails. The most urgent appears to be from your boss about the quarterly report due tomorrow.
User: Mark that as read and I'll look at it right away.
Assistant: [Uses mark-as-read tool]

2. Búsqueda y organización del correo electrónico

Assistant: Would you like me to find specific emails for you?
User: Yes, find all emails from john@example.com about the project budget.
Assistant: [Uses search-emails tool with query "from:john@example.com project budget"]
Assistant: I found 3 emails from John about the project budget. Would you like me to create a label for these?
User: Yes, create a "Budget" label and move them there.
Assistant: [Uses create-label tool followed by move-email tool for each email]

3. Redacción del correo electrónico

Assistant: Would you like me to draft an email for you?
User: Yes, write a follow-up email to the marketing team about our campaign results.
Assistant: [Drafts email content]
Assistant: Here's a draft. Would you like me to send it?
User: Yes, but add Sarah in CC.
Assistant: [Uses send-email tool with the drafted content and CC]

Consideraciones específicas de Gmail

Convenciones de nomenclatura de etiquetas

Gmail tiene requisitos específicos para los nombres de las etiquetas:

Los nombres de las etiquetas distinguen entre mayúsculas y minúsculas
Es posible que no se permitan algunos caracteres especiales
No se pueden crear ni eliminar etiquetas del sistema (como BANDEJA DE ENTRADA, Enviados, Papelera)
Las etiquetas anidadas se representan con una barra diagonal (por ejemplo, "Proyectos/ProyectoX")

Formato de ID de correo electrónico

El formato de ID de correo electrónico utilizado por este servidor MCP es:

email://message/{account}_{mailbox}_{id}

Al utilizar herramientas que requieren una ID de correo electrónico (como mark-as-read o move-email ), asegúrese de utilizar la URI del recurso completa devuelta por las herramientas de recuperación de correo electrónico.

Consideraciones de seguridad

El servidor almacena las credenciales OAuth2 localmente en el directorio ~/.gmail_imap_mcp_credentials
Nunca comparta sus archivos client_secret.json o token
El servidor solo se conecta al servidor IMAP de Gmail mediante conexiones seguras
Los archivos adjuntos de correo electrónico se descargan en el directorio downloads de forma predeterminada.
Tenga cuidado al utilizar el servidor en entornos compartidos para proteger los datos del correo electrónico

Solución de problemas

Problemas de autenticación

Asegúrese de que su client_secret.json esté ubicado correctamente en el directorio ~/.gmail_imap_mcp_credentials
Comprueba que has habilitado la API de Gmail en tu proyecto de Google Cloud
Intente volver a autenticarse si su token ha expirado
Si ve errores de "Sistema de archivos de solo lectura", asegúrese de que el directorio de credenciales se pueda escribir.

Problemas de conexión

Verificar su conexión a Internet
Asegúrese de que su cuenta de Google no tenga restricciones de seguridad que puedan bloquear el acceso IMAP
Comprueba si necesitas habilitar "Acceso a aplicaciones menos seguras" en la configuración de tu cuenta de Google.

Problemas con el envío de correo electrónico

Verifique que su cuenta de Gmail permita el acceso SMTP
Comprueba si necesitas habilitar "Acceso a aplicaciones menos seguras" en la configuración de tu cuenta de Google.
Asegúrese de que los archivos adjuntos no sean demasiado grandes (Gmail tiene un límite de 25 MB)

Problemas de gestión de etiquetas

Si falla la creación de etiquetas, verifique si la etiqueta ya existe (distingue entre mayúsculas y minúsculas)
No se pueden crear ni eliminar etiquetas del sistema
Asegúrese de que los nombres de las etiquetas sigan las convenciones de nomenclatura de Gmail

Problemas de movimiento de correo electrónico

Si falla el movimiento de correos electrónicos entre etiquetas, asegúrese de que existan las etiquetas de origen y de destino
Verifique que el formato del ID de correo electrónico sea correcto
Verifique que tenga permisos suficientes para modificar el correo electrónico

Problemas de análisis de ID de correo electrónico

Si las operaciones en los ID de correo electrónico fallan, asegúrese de estar utilizando el URI del recurso completo
El sistema analiza la última parte del URI como el ID de correo electrónico real
El formato debe ser: email://message/{account}_{mailbox}_{id}

Licencia

Licencia MIT

Apoyo

Para problemas y solicitudes de funciones, abra un problema en el repositorio de GitHub.

Interfaz de línea de comandos

Además del servidor MCP, este paquete también proporciona una interfaz de línea de comandos (CLI) para la interacción directa con las cuentas de Gmail.

Instalación

La CLI se instala automáticamente cuando instala el paquete:

pip install -e .

Comandos disponibles

1. Autenticar una cuenta de Gmail

gmail-imap-cli authenticate your.email@gmail.com

2. Responder a un mensaje específico

gmail-imap-cli reply-to-message your.email@gmail.com 12345 "Thanks for your email." --mailbox INBOX --html "<p>Thanks for your email.</p>" --attachments /path/to/file1.pdf /path/to/file2.docx

3. Responder a un hilo

gmail-imap-cli reply-to-thread your.email@gmail.com 12345 "Let's continue this discussion." --mailbox INBOX --html "<p>Let's continue this discussion.</p>" --attachments /path/to/file.pdf

Argumentos de la CLI

La CLI admite los siguientes argumentos para responder a mensajes e hilos:

account : Cuenta de Gmail para utilizar
email_id / thread_id : ID de correo electrónico/hilo al que responder
body : Cuerpo del mensaje de respuesta (texto sin formato)
--mailbox : Buzón que contiene el correo electrónico/hilo (predeterminado: BANDEJA DE ENTRADA)
--html : versión HTML del cuerpo de la respuesta
--attachments : Una o más rutas de archivos para adjuntar a la respuesta

Integrations

Servidor IMAP MCP de Gmail

Características

Prerrequisitos

Instalación

Instalar desde la fuente

Configurar el proyecto de Google Cloud

Mejoras recientes

Funcionalidad de búsqueda mejorada

Procesamiento de correo electrónico del formulario de contacto

Manejo de JSON con comillas invertidas

Guía de escritorio de Claude

Herramientas y funciones clave

1. Funciones de respuesta (CRÍTICAS)

2. Recuperación de contenido de correo electrónico

Mejores prácticas para Claude

Casos especiales

Correos electrónicos del formulario de contacto

ID de correo electrónico y URI de recursos

Flujo de trabajo recomendado

Referencia de herramientas

Autenticación

Recuperación de correo electrónico

Envío de correo electrónico

Gestión de etiquetas

Organización del correo electrónico

Ejemplos de uso avanzado

Búsqueda mejorada con rango de fechas y etiqueta

Reciba correos electrónicos no leídos con filtrado adicional

Buscar con consultas complejas de Gmail

Detalles de arquitectura e implementación

Almacenamiento de credenciales

Implementación de IMAP

Formato de ID de correo electrónico

Contribuyendo

Uso

Iniciando el servidor

Autenticación de cuentas de Gmail

Herramientas y ejemplos disponibles

Autenticación

1. autenticar-gmail

Recuperación y búsqueda de correo electrónico

2. búsqueda de correos electrónicos

3. obtener correos electrónicos no leídos

Redacción y envío de correos electrónicos

4. enviar correo electrónico

5. responder al mensaje

6. responder al hilo

Gestión de etiquetas

7. crear-etiqueta

8. eliminar etiqueta

9. etiquetas de lista

Organización del correo electrónico

10. mover correo electrónico

Manejo de archivos adjuntos

11. archivo adjunto de descarga

Gestión del estado del correo electrónico

12. marcar como leído

13. marcar como no leído

Indicaciones disponibles

1. resumir correos electrónicos

Integración con asistentes de IA

Conexión con asistentes de IA

Escritorio de Claude

IDE de windsurf

Casos de uso comunes

1. Clasificación de correo electrónico

2. Búsqueda y organización del correo electrónico

3. Redacción del correo electrónico

Consideraciones específicas de Gmail

Convenciones de nomenclatura de etiquetas

Formato de ID de correo electrónico

Consideraciones de seguridad

Solución de problemas

Problemas de autenticación

Problemas de conexión

Problemas con el envío de correo electrónico

Problemas de gestión de etiquetas

Problemas de movimiento de correo electrónico

Problemas de análisis de ID de correo electrónico