Gmail MCP server

Um servidor MCP super simples e pequeno para gmail em python

GitHubExperimente este MCPPatrocinado

Documentação

claude-gmail-mcp

PyPI

Um servidor Gmail MCP super compacto para Claude Code. Permite que o Claude envie, pesquise e leia e-mails do Gmail em seu nome.

Dois backends são suportados e selecionados automaticamente na inicialização:

  • Gmail API (OAuth) — recomendado. Sem senha de aplicativo. Pesquisa em lote. URLs diretas do Gmail web em cada resultado.
  • SMTP/IMAP (senha de aplicativo) — configuração mais simples. Alternativa quando o token OAuth não está presente.

Eu precisava de algo para meus projetos — havia vários por aí que pareciam super complicados. Então por que não deixar o Claude CLI construir um para mim :-p

Pré-requisitos

  • uv instalado
  • Uma das opções:
    • Um cliente OAuth do Google Cloud (aplicativo de desktop) — para o backend da API, OU
    • Uma Senha de aplicativo do Gmail — para o backend SMTP/IMAP

Instalação (backend Gmail API — recomendado)

  1. No Google Cloud Console, crie um projeto, ative a Gmail API e configure a tela de consentimento OAuth (Externa, adicione seu Gmail como usuário de teste). Crie um cliente OAuth do tipo Aplicativo de desktop e baixe o JSON de credenciais.

  2. Execute o helper de autenticação, apontando para o arquivo baixado:

    uvx --from claude-gmail-mcp claude-gmail-mcp-auth /path/to/credentials.json

    O navegador abre → faça login → aprove (escopo: gmail.modify). O token de atualização é salvo em ~/.config/claude-gmail-mcp/token.json (permissões 600).

  3. Registre o servidor MCP com o Claude Code (nenhuma variável de ambiente necessária):

    claude mcp add gmail --scope user -- uvx claude-gmail-mcp

Instalação (backend SMTP/IMAP — alternativa)

claude mcp add gmail --scope user \
  -e GMAIL_ADDRESS=you@gmail.com \
  -e GMAIL_APP_PASSWORD=your-app-password \
  -- uvx claude-gmail-mcp

Substitua you@gmail.com e your-app-password pelas suas credenciais reais. Adicione --scope user para instalar apenas no diretório do projeto atual.

Verificação

claude mcp list

Você deve ver gmail listado como servidor configurado. Para ver qual backend está ativo, execute:

uvx claude-gmail-mcp 2>&1 | head -1

Esperado: [gmail-mcp] backend=api ou [gmail-mcp] backend=imap. Ctrl-C para sair.

Seleção de backend

Na inicialização, o servidor escolhe exatamente um backend:

  1. O arquivo de token em GMAIL_TOKEN_PATH (padrão ~/.config/claude-gmail-mcp/token.json) existe → backend API.
  2. Caso contrário, GMAIL_ADDRESS + GMAIL_APP_PASSWORD variáveis de ambiente definidas → backend IMAP.
  3. Caso contrário, as ferramentas retornam um erro de "nenhum backend configurado".

Para forçar a mudança para o backend IMAP quando um arquivo de token existe, defina GMAIL_TOKEN_PATH para um caminho inexistente (ou exclua o arquivo de token).

Uso

Peça ao Claude para enviar um e-mail:

Envie um e-mail para alice@example.com com o assunto "Hello" e o corpo "Hi from Claude!"

Ferramentas expostas:

  • send_email — to, subject, body, opcional cc/bcc, html, attachments (caminhos de arquivos locais; arquivos ilegíveis são ignorados com um aviso).
  • search_emails — queries (uma única string ou lista de strings), max_results (por consulta quando uma lista é passada). Os resultados incluem o ID da mensagem do Gmail em hexadecimal e uma URL direta do Gmail web para cada resultado.
  • read_email — uid (o ID hexadecimal de search_emails). A saída inclui a URL do Gmail web no topo.

Exemplo de pesquisa em lote:

Pesquise no Gmail por "is:unread from:alice" e "is:unread from:bob" — mostre ambos lado a lado.

Claude passa ambas as consultas em uma única chamada de ferramenta. A resposta é dividida por consulta. O backend API executa a etapa de lista em um único roundtrip HTTP; o backend IMAP itera.

Exemplo de anexo:

Envie um e-mail para alice@example.com com o assunto "Report" e anexe ~/Documents/report.pdf

Publicação no PyPI

python -m build && twine upload dist/*

Para Desenvolvimento

git clone https://github.com/pliablepixels/claude-gmail-mcp.git
cd claude-gmail-mcp
uv sync
uv run pytest

Execute o servidor localmente:

uv run claude-gmail-mcp

Teste com o Claude Code usando sua cópia local em vez do pacote publicado:

claude mcp add gmail --scope user \
  -- uv run --directory /path/to/claude-gmail-mcp claude-gmail-mcp

(Para o backend IMAP, adicione -e GMAIL_ADDRESS=... -e GMAIL_APP_PASSWORD=....)