gmail-mcp v1.0.0

Servidor MCP unificado de Google OAuth2 para Gmail con soporte multi-cuenta. Busca, lee, redacta, envía, crea borradores y organiza correos electrónicos en múltiples cuentas de Google de forma fluida.

Características (4 herramientas unificadas)

• gmail_search: Busca correos con la sintaxis de búsqueda oficial de Gmail (is:unread, from:boss@corp.com, subject:invoice, newer_than:2d, has:attachment)

• gmail_read: Lee el contenido completo del correo y sus metadatos (asunto, remitente, texto del cuerpo, HTML, CC, CCO, etiquetas, lista de adjuntos)

• gmail_send: Envía correos o crea borradores (compatible con HTML, CC, CCO, respuestas en hilos y archivos adjuntos)

• gmail_manage: Etiquetado, archivado, gestión de la papelera, marcar como leído/no leído, eliminación permanente e inventario de múltiples cuentas

Related MCP server: Moist

Arquitectura multi-cuenta

Un único cliente OAuth de Google Cloud (credentials.json) puede autenticar varias cuentas de Gmail. Los tokens se almacenan por cuenta en ~/.secrets/gmail/tokens/<account_name>.json.

1. Configurar las credenciales OAuth de Google (una sola vez)

1. Crea un proyecto en Google Cloud Console.

2. Habilita la API de Gmail.

3. Crea un ID de cliente OAuth 2.0 (aplicación de escritorio).

4. Descarga el archivo JSON del secreto de cliente y guárdalo como ~/.secrets/gmail/credentials.json (o define GMAIL_CREDENTIALS_JSON).

2. Autenticar cuentas

Ejecuta la CLI de autorización interactiva para cada cuenta:

gmail-auth default    # Authenticates primary account
gmail-auth work       # Authenticates secondary work account
gmail-auth client_x   # Authenticates any additional account

Lista todas las cuentas autenticadas:

gmail-auth --list

Instalación en clientes MCP (Claude Desktop, OpenCode, Cursor, Windsurf)

Opción 1: Instalación instantánea con uvx (recomendada)

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Steph-ux/gmail-mcp.git", "gmail-mcp"]
    }
  }
}

Opción 2: Mediante pip install

pip install git+https://github.com/Steph-ux/gmail-mcp.git

Luego, en tu configuración de MCP:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp"
    }
  }
}

Opción 3: Clon local (desarrollo)

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["D:\\Steph\\script\\gmail-mcp\\server.py"]
    }
  }
}

Ejemplos de uso

1. Buscar mensajes

# Search in default account:
gmail_search(query='is:unread from:github')

# Search in work account:
gmail_search(account='work', query='subject:invoice newer_than:7d')

2. Leer mensaje

gmail_read(account='work', message_id='18f2a9b4c10d')

3. Enviar correo o crear borrador

# Send direct email:
gmail_send(
    account='default',
    to='colleague@example.com',
    subject='Project Update',
    body_text='Here is the latest status...',
    body_html='<h1>Project Update</h1><p>Here is the latest status...</p>'
)

# Create a draft:
gmail_send(
    account='work',
    to='client@example.com',
    subject='Proposal draft',
    body_text='Please review the proposal.',
    draft=True
)

4. Organizar y gestionar

# Archive email:
gmail_manage(account='work', action='archive', message_id='18f2a9b4c10d')

# Mark as unread:
gmail_manage(account='default', action='mark_unread', message_id='18f2a9b4c10d')

# Move to trash:
gmail_manage(account='default', action='trash', message_id='18f2a9b4c10d')

# List active accounts:
gmail_manage(action='list_accounts')

Pruebas

pytest tests

Licencia

MIT