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

Gmail MCP Server Auto-hospedado

thisstillisntreal/gmail-mcp

Gmail MCP self-hosted com múltiplas contas e controle total

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para Gmail que você controla end-to-end, substituindo o conector nativo do Claude. Suporta múltiplas contas, gerenciamento de threads, drafts, labels e busca — sem enviar e-mails automaticamente, apenas rascunhos revisáveis.

Instalação

$npx convez-ai thisstillisntreal/gmail-mcp

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
1
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar Gmail ao Claude Code com controle total sobre credenciais
  • Gerenciar múltiplas contas de e-mail simultaneamente via MCP
  • Automatizar busca, leitura e organização de threads e labels
  • Criar e gerenciar rascunhos de e-mail de forma programática

Veredito

Solução técnica sólida para quem precisa de acesso programático ao Gmail com segurança de primeira parte. Requer setup manual de OAuth e gerenciamento de tokens, mas oferece flexibilidade e controle ausentes no conector padrão — ideal para workflows com múltiplas contas.

README

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

gmail-mcp

Self-hosted Gmail MCP server. Drop-in replacement for the claude.ai Gmail connector that you control end-to-end — bring your own OAuth credentials, run multiple accounts side by side, extend with new tools.

Tools: search_threads, get_thread, list_drafts, create_draft, list_labels, create_label, update_label, delete_label, label_thread, unlabel_thread, label_message, unlabel_message.

1. Get Google OAuth credentials

One-time per Google project, reusable across all the Gmail accounts you want to connect.

  1. Go to https://console.cloud.google.com/projectcreate and create a project (or pick an existing one).
  2. APIs & Services → Library → Gmail API → Enable.
  3. APIs & Services → OAuth consent screen.
    • User type: External.
    • App name + your email. Save.
    • Scopes: add https://www.googleapis.com/auth/gmail.modify and https://www.googleapis.com/auth/gmail.labels.
    • Test users: add every Gmail address you intend to connect (you can stay in "Testing" mode forever — no need to publish).
  4. APIs & Services → Credentials → Create Credentials → OAuth client ID.
    • Application type: Desktop app. Name it anything.
    • Download the JSON.

2. Install

git clone https://github.com/<you>/gmail-mcp.git
cd gmail-mcp
uv sync

3. Authorize each account

Each Gmail account gets its own folder under ~/.config/gmail-mcp/<account>/. Place the OAuth client JSON there as credentials.json, then run the auth CLI. The account name is yours to pick — personal, work, acme, whatever.

PowerShell:

mkdir $env:USERPROFILE\.config\gmail-mcp\personal
copy <downloaded-oauth-client.json> $env:USERPROFILE\.config\gmail-mcp\personal\credentials.json
uv run gmail-mcp-auth --account personal

Bash:

mkdir -p ~/.config/gmail-mcp/personal
cp <downloaded-oauth-client.json> ~/.config/gmail-mcp/personal/credentials.json
uv run gmail-mcp-auth --account personal

Each gmail-mcp-auth run opens a browser. Sign in as the matching Google account. The refresh token is saved to token.json in that account's folder. Repeat with a different --account name for every additional inbox.

4. Wire into Claude Code

Edit ~/.claude.json (or use claude mcp add). Register one server per account, each with its own GMAIL_MCP_ACCOUNT env var:

{
  "mcpServers": {
    "gmail-personal": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/gmail-mcp", "run", "gmail-mcp"],
      "env": { "GMAIL_MCP_ACCOUNT": "personal" }
    },
    "gmail-work": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/gmail-mcp", "run", "gmail-mcp"],
      "env": { "GMAIL_MCP_ACCOUNT": "work" }
    }
  }
}

Restart Claude Code. Both connectors should appear in /mcp as already-connected.

Notes

  • gmail.modify scope is what lets you label/archive/draft. We deliberately don't request gmail.send — the server can't send mail, only draft it. Remove the gmail.labels scope if you only need read+draft.
  • $GMAIL_MCP_HOME overrides the config root if you want it somewhere other than ~/.config/gmail-mcp.
  • Token expiry: refresh tokens from a "Testing"-mode OAuth consent screen expire after 7 days. Either publish the consent screen (1-click for internal Gmail-only apps) or re-run gmail-mcp-auth weekly.
  • Send tool isn't implemented on purpose — every draft is reviewable in Gmail before you hit send. If you want one, add a send_message tool that calls service.users().messages().send() with the gmail.send scope.
Ver o original no GitHub

Bom para

Relacionados