MCP Email Service

Un servicio para gestionar múltiples cuentas de correo electrónico de varios proveedores como 163, Gmail, QQ y Outlook.

GitHub
43
Prueba este MCPPatrocinado

Documentación

mail-use

Correo electrónico, como algo que un agente de IA puede operar de verdad. Una CLI sobre Gmail, QQ, 163, Outlook y cualquier servidor IMAP/SMTP — cada comando habla JSON, cada uno destructivo es de prueba en seco hasta que pases --confirm.

mail-use code --json          # the newest verification code, one live pass
mail-use email recent --format compact --json
mail-use email delete --from newsletter@shop.com --confirm --json

Parte de la familia *-use — pequeñas herramientas que dan a cada agente manos sobre una cosa real.

Por qué esto y no un fragmento de IMAP

  • Un contrato JSON estable, no texto extraído. Cada respuesta lleva success: boolean, y los fallos llevan error_code de un conjunto fijo (auth_failed, folder_not_found, imap_error, …). Documentado en docs/CLI_JSON_CONTRACT.md.
  • Te dice cuándo podría estar equivocado. Las lecturas en caché reportan from_cache, cache_age_seconds y cache_stale, y una instantánea lo suficientemente antigua como para significar "nada se está sincronizando" se rechaza en favor de una obtención en vivo. Una bandeja de entrada vacía nunca es un silencioso "no llegó nada".
  • Destructivo solo con consentimiento. delete / mark / move / send devuelven una vista previa de prueba en seco — agrupada por cuenta y carpeta, con asuntos de muestra — y no cambian nada hasta --confirm. --all-folders omite Enviados/Borradores/Spam/Papelera a menos que se pida.
  • Construido para presupuestos de tokens. --format compact proyecta cada correo a los diez campos que valen la pena escanear (~30% más pequeño que la forma completa), --with-preview pliega un fragmento del cuerpo en la llamada de listado, y el lote show reutiliza una conexión IMAP.
  • Suficientemente rápido para llamar en un bucle. Un demonio persistente agrupa conexiones IMAP y sincroniza a SQLite local en segundo plano: cinco llamadas secuenciales email list pasan de 25s a 0.83s. Ver la tabla a continuación.
  • MCP también. mail-use mcp config --json imprime una entrada lista para pegar; el servidor expone 16 herramientas con los mismos valores predeterminados de prueba en seco.

Renombrado de Mailbox a mail-use. El comando ahora es mail-use; mailbox todavía funciona como alias, y tu configuración en ~/.config/mailbox no se toca.

Proveedores compatibles

163 / 126 · QQ · Gmail · Outlook / Hotmail · cualquier servidor IMAP+SMTP personalizado.

La búsqueda se comporta de manera diferente según el proveedor y la CLI lo dice: Gmail busca cuerpos del lado del servidor vía X-GM-RAW, mientras que QQ/163/Outlook tienen búsqueda IMAP TEXT rota, por lo que --query recurre a coincidir solo asunto + remitente. Usa --from / --subject allí para resultados predecibles.

Instalación

Una línea, sin npm, sin Node

curl -fsSL https://raw.githubusercontent.com/leeguooooo/mail-use/main/install.sh | sh
mail-use --help

Descarga el binario precompilado para tu plataforma (macOS arm64/x64, Linux x64) desde el último lanzamiento de GitHub, verifica su checksum, e instala en ~/.local/bin. Fija una versión con MAIL_USE_VERSION=v2.11.2, o cambia el directorio con MAIL_USE_INSTALL_DIR=....

El instalador también coloca un enlace simbólico mailbox junto a él, para que los scripts escritos con el nombre antiguo sigan funcionando.

No hay paquete npm. La distribución es solo binarios de GitHub Release — eso mantiene los lanzamientos libres de NPM_TOKEN y avisos de 2FA, y mantiene la instalación libre de un toolchain de Node. Los paquetes @leeguoo/mailbox-cli previos al renombrado en npm están congelados y ya no se actualizan.

Actualización

mail-use upgrade --check     # is there a newer release?
mail-use upgrade             # download, verify sha256, replace in place, restart the daemon
mail-use upgrade --tag v3.1.0   # pin an exact release (also the way to roll back)

Cuando el demonio está en ejecución, nota nuevos lanzamientos por ti: un GET no autenticado a la API de lanzamientos de GitHub por día (MAILBOX_UPDATE_CHECK_HOURS, 0 lo desactiva), mostrado como update en mail-use daemon status --json. Solo informa — nunca descarga o instala nada.

upgrade nunca es automático y nunca se ejecuta solo: una herramienta que reemplaza silenciosamente su propio ejecutable es una sorpresa en la cadena de suministro, no una conveniencia. Se niega a instalar un tarball cuyo .sha256 publicado no coincide, y se niega a ejecutarse desde un checkout de desarrollo (donde process.execPath es tu node). Volver a ejecutar la línea curl … install.sh | sh hace el mismo trabajo.

Como una habilidad de IA (Claude Code / Cursor / etc.)

# Project scope — installs into ./.claude/skills/mail-use (or ./.cursor/skills/...):
npx skills add leeguooooo/mail-use --skill mail-use

# User scope — installs into ~/.claude/skills/mail-use:
npx skills add leeguooooo/mail-use --skill mail-use -g

La habilidad asume que la CLI está en PATH (instala vía el curl … install.sh | sh anterior). Para la mayor aceleración, también ejecuta mail-use daemon install una vez.

Servidor MCP (Claude Desktop / Code / Cursor)

mail-use mcp config --json   # prints a paste-ready mcpServers entry

Desde el código fuente (desarrollo)

pnpm install
pnpm test

# build a local platform binary into dist/mail-use
pnpm build:binary

Si una ejecución de pruebas se interrumpe (tarea del editor eliminada, sesión de agente cerrada), sus trabajadores de Vitest pueden quedar atrás y retener memoria. Verifica con pgrep -fl vitest y mata lo que quede.

Configurar cuentas

mkdir -p ~/.config/mailbox
cp examples/accounts.example.json ~/.config/mailbox/auth.json

Ubicaciones de configuración:

  • Credenciales: ~/.config/mailbox/auth.json
  • Otras configuraciones: ~/.config/mailbox/config.toml

Comandos comunes

# CLI help
mail-use --help

# newest verification code across all accounts, one live pass
mail-use code --json

# list accounts
mail-use account list --json

# list unread emails (cache by default; --from filters cache-side)
mail-use email list --unread-only --limit 20 --json
mail-use email list --account-id my_account_id --from "newsletter" --json

# show one email (response includes list_unsubscribe when the header is set)
mail-use email show 123456 --account-id my_account_id --json

# mark read (use --dry-run to validate first)
mail-use email mark 123456 --read --account-id my_account_id --folder INBOX --dry-run --json
mail-use email mark 123456 --read --account-id my_account_id --folder INBOX --confirm --json

# delete
mail-use email delete 123456 --account-id my_account_id --folder INBOX --confirm --json

# bulk mutate by sender or subject (no UID list needed)
mail-use email mark --from "support@npmjs.com" --read --confirm --account-id my_account_id --json
mail-use email delete --from "newsletter" --account-id my_account_id --json    # dry-run preview
mail-use email delete --subject "[ad]" --account-id my_account_id --confirm --json

Caché + sincronización

  • Base de datos de caché predeterminada: ~/.local/share/mailbox/email_sync.db
  • El listado usa caché por defecto cuando es posible. Agrega --live para forzar IMAP.
mail-use sync status --json
mail-use sync force --json
mail-use sync init
mail-use sync daemon

Demonio persistente (llamadas CLI 5-30× más rápidas)

Cada invocación de una sola vez gasta de otro modo 1-3s en TCP+TLS+IMAP LOGIN. Con el demonio en ejecución, las llamadas reutilizan conexiones agrupadas y una sincronización SQLite en segundo plano significa que email list normalmente no toca IMAP en absoluto.

El instalador curl … install.sh | sh configura esto por ti cuando las cuentas ya están configuradas (MAIL_USE_NO_DAEMON=1 opta por no participar). De lo contrario:

mail-use daemon install      # autostart at login (macOS launchd / Linux systemd-user)
mail-use daemon status --json
mail-use daemon reload       # drop pooled connections after editing auth.json

Medido en Gmail INBOX, M2 MacBook sobre WAN residencial:

OperaciónSin demonioDemonio (--live)Demonio (en caché)
email list único5.0s1.0s0.17s
email folders5.0s0.85sn/a
5 email list secuenciales25s5.3s0.83s
3 email show en paralelo~15s2.7s0.88s

Huella de recursos (muchas sesiones de agente en una máquina)

El demonio es un proceso por usuario, compartido por cada sesión de agente a través de un socket Unix — así que más sesiones no significan más conexiones IMAP. Medido en reposo en macOS con 3 cuentas conectadas:

CPU en reposo~0.15%
RSS en reposo3-15 MB
Conexionesmáx. 3 por cuenta (MAILBOX_POOL_MAX), reducidas a 1 después de 10 min en reposo
12 llamadas concurrentes1.6s de tiempo real, el grupo se mantuvo en 1 conexión por cuenta

Perillas, si los valores predeterminados no te convienen:

EnvPredeterminadoEfecto
MAILBOX_POOL_MAX3Máx. conexiones IMAP concurrentes por cuenta
MAILBOX_POOL_IDLE_MS600000Cierra conexiones inactivas este tiempo (0 desactiva la reducción)
MAILBOX_POOL_KEEP_WARM1Conexiones por cuenta mantenidas calientes a través de la reducción
MAILBOX_NO_DAEMONsin definir1 hace que la CLI omita el demonio por completo
MAILBOX_UPDATE_CHECK_HOURS24Verificación de actualización pasiva del demonio (0 desactiva)

Guía de uso para IA

Si estás integrando esta CLI en un agente de IA, comienza aquí:

  • docs/AI_SKILL_MAIL_USE.md

Integración con OpenClaw

Este repositorio incluye una habilidad de OpenClaw en skills/mail-use/SKILL.md.

OpenClaw carga habilidades desde:

  • <workspace>/skills
  • ~/.openclaw/skills

Ayudante de enlace rápido (enlace simbólico en ~/.openclaw/skills):

./scripts/link_openclaw_skill.sh

Forzar reemplazo de un enlace existente:

./scripts/link_openclaw_skill.sh --force

Para usar este repositorio sin copiar archivos, agrega el directorio de habilidades del repositorio a skills.load.extraDirs en ~/.openclaw/openclaw.json:

{
  "skills": {
    "load": {
      "extraDirs": [
        "/path/to/mcp-email-service/skills"
      ]
    }
  }
}

OpenClaw maneja la entrega de canales y la programación; mail-use devuelve salidas JSON estructuradas y resúmenes de texto opcionales.

Verifica que OpenClaw haya recogido la habilidad:

openclaw skills list --eligible
openclaw skills check

La familia *-use

CLIs pequeñas y componibles que dan a un agente de IA manos sobre una cosa real. Misma forma en todas partes: curl … install.sh | sh para instalar, npx skills add leeguooooo/<name> para enseñar a tu agente, JSON en stdout.

RepoDa a tu agente
chrome-useUn navegador real — sesiones iniciadas, formularios, scraping, capturas de pantalla
mail-useCorreo electrónico — leer, buscar, enviar, triage en Gmail / QQ / 163 / cualquier IMAP
iphone-useUn iPhone real — tocar, escribir, capturar, extraer datos del dispositivo
wechat-useWeChat en macOS — enviar mensajes, consultar contactos e historial
discord-useDiscord — mensajes, canales, foros, webhooks (solo REST, Rust)
cookie-useMuchas cuentas iniciadas por sitio — capturar, cambiar, aplicar sesiones
profile-useTu perfil personal, de forma segura — llenar formularios de registro / KYC / pago
bitwarden-useBitwarden / Vaultwarden — inicio de sesión sin cabeza con passkey (FIDO2)
chatgpt-useTu suscripción de ChatGPT como backend de agente de codificación — sin clave API
computer-useEl escritorio de macOS en sí
pixcake-useSondeo de PixCake de solo lectura — instantánea / diff / inspección de SQLite

Contrato

  • docs/CLI_JSON_CONTRACT.md

Construido por leeguooooo — notas de campo sobre agentes de IA, ingeniería inversa y Cloudflare Workers en blog.misonote.com · sigue en X @leeguooooo