MCP Email Service

Um serviço para gerenciar múltiplas contas de e-mail de vários provedores como 163, Gmail, QQ e Outlook.

Documentação

mail-use

E-mail, como algo que um agente de IA pode realmente operar. Um CLI sobre Gmail, QQ, 163, Outlook e qualquer caixa IMAP/SMTP — cada comando fala JSON, e toda ação destrutiva é dry-run até você passar --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 da família *-use — ferramentas pequenas que dão a cada agente mãos em uma coisa real.

Por que isso e não um snippet IMAP

Um contrato JSON estável, não texto raspado. Cada resposta carrega success: boolean, e falhas carregam error_code de um conjunto fixo (auth_failed, folder_not_found, imap_error, …). Documentado em docs/CLI_JSON_CONTRACT.md.
Ele avisa quando pode estar errado. Leituras em cache relatam from_cache, cache_age_seconds e cache_stale, e um snapshot antigo o suficiente para significar "nada está sincronizando" é recusado em favor de uma busca ao vivo. Uma caixa de entrada vazia nunca é um silencioso "nada chegou".
Destrutivo apenas com consentimento. delete / mark / move / send retornam uma prévia dry-run — agrupada por conta e pasta, com assuntos de exemplo — e não mudam nada até --confirm. --all-folders pula Enviados/Rascunhos/Lixo/Lixeira a menos que solicitado.
Feito para orçamentos de tokens. --format compact projeta cada e-mail para os dez campos que valem a pena escanear (~30% menor que o formato completo), --with-preview dobra um trecho do corpo na chamada de listagem, e o lote show reutiliza uma conexão IMAP.
Rápido o suficiente para chamar em loop. Um daemon persistente agrupa conexões IMAP e sincroniza para SQLite local em segundo plano: cinco chamadas sequenciais email list vão de 25s para 0,83s. Veja a tabela abaixo.
MCP também. mail-use mcp config --json imprime uma entrada pronta para colar; o servidor expõe 16 ferramentas com os mesmos padrões dry-run.

Renomeado de Mailbox para mail-use. O comando agora é mail-use; mailbox ainda funciona como alias, e sua configuração em ~/.config/mailbox permanece intocada.

Provedores suportados

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

A busca se comporta de forma diferente por provedor e o CLI diz isso: o Gmail busca corpos no lado do servidor via X-GM-RAW, enquanto QQ/163/Outlook têm busca IMAP TEXT quebrada, então --query recorre a corresponder apenas assunto + remetente. Use --from / --subject lá para resultados previsíveis.

Instalação

Uma linha, sem npm, sem Node

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

Baixa o binário pré-compilado para sua plataforma (macOS arm64/x64, Linux x64) do último GitHub Release, verifica seu checksum e instala em ~/.local/bin. Fixe uma versão com MAIL_USE_VERSION=v2.11.2, ou mude o diretório com MAIL_USE_INSTALL_DIR=....

O instalador também cria um symlink mailbox ao lado, para que scripts escritos com o nome antigo continuem funcionando.

Não há pacote npm. A distribuição é apenas binários de GitHub Release — isso mantém os lançamentos livres de NPM_TOKEN e prompts de 2FA, e mantém a instalação livre de um toolchain Node. Os pacotes @leeguoo/mailbox-cli pré-renomeação no npm estão congelados e não são mais atualizados.

Atualização

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)

Quando o daemon está em execução, ele percebe novos lançamentos para você: um GET não autenticado para a API de releases do GitHub por dia (MAILBOX_UPDATE_CHECK_HOURS, 0 desativa), exibido como update em mail-use daemon status --json. Ele apenas relata — nunca baixa ou instala nada.

upgrade nunca é automático e nunca roda sozinho: uma ferramenta que silenciosamente substitui seu próprio executável é uma surpresa na cadeia de suprimentos, não uma conveniência. Ele se recusa a instalar um tarball cujo .sha256 publicado não corresponde, e se recusa a rodar a partir de um checkout de desenvolvimento (onde process.execPath é seu node). Re-executar a linha curl … install.sh | sh faz o mesmo trabalho.

Como uma Skill 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

A skill assume que o CLI está em PATH (instale via curl … install.sh | sh acima). Para o maior ganho de velocidade, também execute mail-use daemon install uma vez.

Servidor MCP (Claude Desktop / Code / Cursor)

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

A partir do código-fonte (desenvolvimento)

pnpm install
pnpm test

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

Se uma execução de teste for interrompida (tarefa do editor morta, sessão do agente fechada), seus workers do Vitest podem ficar para trás e segurar memória. Verifique com pgrep -fl vitest e mate o que restar.

Configurar contas

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

Locais de configuração:

Credenciais: ~/.config/mailbox/auth.json
Outras configurações: ~/.config/mailbox/config.toml

Comandos comuns

# 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

Cache + sincronização

Banco de cache padrão: ~/.local/share/mailbox/email_sync.db
Listagem usa cache por padrão quando possível. Adicione --live para forçar IMAP.

mail-use sync status --json
mail-use sync force --json
mail-use sync init
mail-use sync daemon

Daemon persistente (chamadas CLI 5-30× mais rápidas)

Cada invocação avulsa gasta de outra forma 1-3s em TCP+TLS+IMAP LOGIN. Com o daemon em execução, chamadas reutilizam conexões agrupadas e uma sincronização SQLite em segundo plano significa que email list geralmente não toca IMAP.

O instalador curl … install.sh | sh configura isso para você quando contas já estão configuradas (MAIL_USE_NO_DAEMON=1 opta por sair). Caso contrário:

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 na caixa de entrada do Gmail, MacBook M2 em WAN residencial:

Operação	Sem daemon	Daemon (`--live`)	Daemon (cache)
Único `email list`	5,0s	1,0s	0,17s
`email folders`	5,0s	0,85s	n/a
5 sequenciais `email list`	25s	5,3s	0,83s
3 paralelos `email show`	~15s	2,7s	0,88s

Pegada de recursos (muitas sessões de agente em uma máquina)

O daemon é um processo por usuário, compartilhado por cada sessão de agente através de um socket Unix — então mais sessões não significam mais conexões IMAP. Medido ocioso no macOS com 3 contas conectadas:


CPU ociosa	~0,15%
RSS ocioso	3-15 MB
Conexões	máx. 3 por conta (`MAILBOX_POOL_MAX`), reduzidas de volta para 1 após 10 min ociosos
12 chamadas concorrentes	1,6s de tempo real, pool permaneceu em 1 conexão por conta

Ajustes, se os padrões não servirem para você:

Env	Padrão	Efeito
`MAILBOX_POOL_MAX`	`3`	Máx. de conexões IMAP concorrentes por conta
`MAILBOX_POOL_IDLE_MS`	`600000`	Fecha conexões ociosas por esse tempo (`0` desativa a redução)
`MAILBOX_POOL_KEEP_WARM`	`1`	Conexões por conta mantidas aquecidas através da redução
`MAILBOX_NO_DAEMON`	não definido	`1` faz o CLI pular o daemon completamente
`MAILBOX_UPDATE_CHECK_HOURS`	`24`	Verificação de atualização passiva do daemon (`0` desativa)

Guia de uso para IA

Se você está integrando este CLI a um agente de IA, comece aqui:

docs/AI_SKILL_MAIL_USE.md

Integração com OpenClaw

Este repositório inclui uma skill OpenClaw em skills/mail-use/SKILL.md.

O OpenClaw carrega skills de:

<workspace>/skills
~/.openclaw/skills

Ajudante de link rápido (symlink em ~/.openclaw/skills):

./scripts/link_openclaw_skill.sh

Forçar substituição de um link existente:

./scripts/link_openclaw_skill.sh --force

Para usar este repositório sem copiar arquivos, adicione o diretório de skills do repositório a skills.load.extraDirs em ~/.openclaw/openclaw.json:

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

O OpenClaw lida com entrega de canais e agendamento; mail-use retorna saídas JSON estruturadas e resumos de texto opcionais.

Verifique se o OpenClaw pegou a skill:

openclaw skills list --eligible
openclaw skills check

A família `*-use`

CLIs pequenos e compostos que dão a um agente de IA mãos em uma coisa real. Mesma forma em todos os lugares: curl … install.sh | sh para instalar, npx skills add leeguooooo/<name> para ensinar seu agente, JSON na saída padrão.

Repo	Dá ao seu agente
chrome-use	Um navegador real — sessões logadas, formulários, raspagem, capturas de tela
mail-use	E-mail — ler, buscar, enviar, triar em Gmail / QQ / 163 / qualquer IMAP
iphone-use	Um iPhone real — tocar, digitar, capturar tela, puxar dados do dispositivo
wechat-use	WeChat no macOS — enviar mensagens, consultar contatos e histórico
discord-use	Discord — mensagens, canais, fóruns, webhooks (somente REST, Rust)
cookie-use	Muitas contas logadas por site — capturar, alternar, aplicar sessões
profile-use	Seu perfil pessoal, com segurança — preencher formulários de cadastro / KYC / checkout
bitwarden-use	Bitwarden / Vaultwarden — login headless com passkey (FIDO2)
chatgpt-use	Sua assinatura do ChatGPT como backend de agente de codificação — sem chave de API
computer-use	O desktop macOS em si
pixcake-use	Sondagem PixCake somente leitura — snapshot / diff / inspeção SQLite

Contrato

docs/CLI_JSON_CONTRACT.md

Construído por leeguooooo — notas de campo sobre agentes de IA, engenharia reversa e Cloudflare Workers em blog.misonote.com · siga no X @leeguooooo