convez.ai
MCP ServerIntegração & APIsIntermediário
manuelfedele

Gmail/IMAP para Claude — Download de Anexos

manuelfedele/gmail-imap

Acesso completo a email com anexos salvos em disco para IA agir

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra Gmail e qualquer caixa IMAP/SMTP ao Claude, com suporte robusto a download de anexos. Permite ler, buscar, enviar e responder emails com threading correto, gravando arquivos em disco para processamento por outros agentes.

Instalação

$npx convez-ai manuelfedele/gmail-imap

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
5
Contribuidores
2

Casos de uso

  • Processar invoices e contratos em anexos de email automaticamente
  • Buscar e extrair dados de planilhas e PDFs recebidos
  • Enviar respostas de email inteligentes com threading preservado
  • Integrar email como fonte de dados para workflows de IA

Veredito

Solução sólida e diferenciada no mercado por resolver o problema real de anexos em integrações de email com IA. Implementação em Go sem dependências é apropriada para produção; requer apenas configuração de App Password do Gmail.

README

A tradução para o português deste README ainda está na fila.

gmail-imap

A single-binary MCP server for Gmail (and any IMAP/SMTP mailbox) — with first-class attachment download. Written in Go, no runtime dependencies.

License: MIT build

The attachment story is the headline. Most email integrations for AI agents stop at metadata: they tell the model "this message has 3 attachments" and that's it. This one writes the actual files to disk and hands the agent absolute paths it can pipe into every other tool — Read, PDF/XLSX/DOCX skills, OCR, your own scripts. Invoices, contracts, photos, CSVs — they land somewhere the agent can act on them.

Plus the rest of the boring-but-essential mailbox surface: read, search, send, reply with proper threading, star, move. No SaaS dependencies, no OAuth dance — just an App Password.

You: "Open the latest email from my accountant and download the PDFs."

Claude → gmail_messages_search { from: "accountant@firm.com", limit: 1 }
Claude → gmail_message_attachments_save { uid: 4128 }
         ↳ saved 2 files to ~/.gmail-imap/attachments/INBOX-4128/
             - Invoice_2026_05.pdf  (124 KB)
             - Receipts_April.pdf   (812 KB)
Claude → Read("~/.gmail-imap/attachments/INBOX-4128/Invoice_2026_05.pdf")
         ↳ "Total due: €2,340. Payment by 2026-05-31. Reference: INV-2845."

Install

Download a prebuilt binary from the build workflow artifacts — Linux, macOS and Windows, amd64 and arm64 — or build from source:

go build -o gmail-imap .
# or
go install github.com/manuelfedele/gmail-imap@latest

Configuration

Generate a Gmail App Password at https://myaccount.google.com/apppasswords (requires 2FA).

Option 1 — config file at ~/.gmail-imap/config.json (override the path with GMAIL_IMAP_CONFIG):

{
  "username": "you@gmail.com",
  "appPassword": "xxxxxxxxxxxxxxxx",
  "fromName": "Your Name"
}

All fields:

FieldDefaultNotes
username—required
appPassword—required; spaces are stripped
fromusernamesender address
fromName—display name on sent mail
replyTo—Reply-To header on sent mail
imap.host / imap.port / imap.secureimap.gmail.com / 993 / true
smtp.host / smtp.port / smtp.securesmtp.gmail.com / 465 / truesecure=false uses STARTTLS
defaultMailboxINBOX
defaultSearchLimit10
attachmentsDir~/.gmail-imap/attachments
requireExplicitSendConfirmationtruesend/reply require confirm=true

Option 2 — environment variables (these win over the config file): GMAIL_USERNAME, GMAIL_APP_PASSWORD, GMAIL_FROM, GMAIL_FROM_NAME, GMAIL_REPLY_TO, GMAIL_IMAP_HOST, GMAIL_IMAP_PORT, GMAIL_IMAP_SECURE, GMAIL_SMTP_HOST, GMAIL_SMTP_PORT, GMAIL_SMTP_SECURE, GMAIL_DEFAULT_MAILBOX, GMAIL_DEFAULT_SEARCH_LIMIT, GMAIL_ATTACHMENTS_DIR, GMAIL_REQUIRE_SEND_CONFIRMATION.

Works with any IMAP/SMTP provider that supports password auth — point imap.host/smtp.host at Fastmail, iCloud, your own server, etc.

Registering the server

The server speaks MCP over stdio. With Claude Code:

claude mcp add gmail-imap -- /path/to/gmail-imap

Or in any MCP client configuration:

{
  "mcpServers": {
    "gmail-imap": {
      "command": "/path/to/gmail-imap"
    }
  }
}

Tools

ToolPurpose
gmail_mailboxes_listList folders/labels
gmail_messages_searchServer-side search; free text plus inline Gmail-style operators; defaults to the last 30 days when no date filter is given
gmail_message_getFull message by UID — body (HTML auto-converted to text when needed) and attachment metadata
gmail_thread_getAll messages in the same conversation, chronological
gmail_message_attachments_saveSave attachments to disk; returns absolute paths
gmail_message_updateMark read/unread, star/unstar
gmail_message_moveMove a message to another mailbox
gmail_message_sendSend a new email (guarded by confirm)
gmail_message_replyReply / reply-all with quoting and proper In-Reply-To/References headers (guarded by confirm)

Search syntax

query accepts free text (terms are ANDed, OR for alternation) and Gmail-style operators which are extracted automatically:

invoice from:billing@example.com is:unread after:2026-01-01 has:attachment

Recognized operators: from:, to:, subject:, has:attachment, is:unread, is:read, is:starred, in:LABEL, before:YYYY-MM-DD, after:YYYY-MM-DD. Explicit tool parameters win over inline operators. Paginate by passing before with the date of the last seen message.

Threading is resolved via standard Message-ID/References headers, so gmail_thread_get works against Gmail and any other IMAP server alike.

Building all platforms

The build workflow runs go vet / go test and cross-compiles static binaries (CGO_ENABLED=0) for linux, darwin and windows on amd64 and arm64 — on every push to main, every tag and every pull request — uploading each binary as a workflow artifact.

# local equivalent
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/gmail-imap-linux-amd64 .

License

MIT

Ver o original no GitHub

Bom para

Relacionados