Gmail MCP

Uma interface padronizada para gerenciar, enviar e recuperar e-mails através da API do Gmail.

Documentação

Gmail MCP Server

Uma implementação de servidor Model Context Protocol (MCP) para a API do Gmail, fornecendo uma interface padronizada para gerenciamento, envio e recuperação de e-mails.

Recursos

Cobertura completa da API do Gmail, incluindo mensagens, conversas, rótulos, rascunhos e configurações
Suporte para envio, criação de rascunhos e gerenciamento de e-mails
Gerenciamento de rótulos com cores personalizáveis e configurações de visibilidade
Operações de conversas para gerenciamento de conversas
Gerenciamento de configurações, incluindo respondedor de férias, IMAP/POP e configurações de idioma
Rastreamento de histórico para alterações na caixa de entrada
Autenticação segura OAuth2 usando credenciais do Google Cloud

Pré-requisitos

Dependências

Para a instalação mais simples, instale o Node.js 18+. Se você quiser compilar localmente, também precisará instalar o pnpm.

Configuração do Google Workspace

Para executar este servidor MCP, você precisará configurar um Cliente da API do Google para sua organização, com cada usuário executando um script para obter seu próprio token de atualização OAuth.

Configuração do Cliente da API do Google (uma vez por organização)

Acesse o Google Cloud Console.
Crie um novo projeto ou selecione um existente.
Ative a API do Gmail para o seu projeto.
Vá para Credenciais e crie um ID de Cliente OAuth 2.0. Escolha "Aplicativo para desktop" como tipo de cliente.
Baixe e salve o JSON das chaves OAuth como ~/.gmail-mcp/gcp-oauth.keys.json. ⚠️ OBSERVAÇÃO: para criar ~/.gmail-mcp/ pelo aplicativo Finder do MacOS, você precisa ativar arquivos ocultos primeiro.
(Opcional) Para instalação em servidor remoto (ex.: usando a CLI do Smithery), anote o CLIENT_ID e o CLIENT_SECRET deste arquivo.

OAuth do Cliente (uma vez por usuário)

Peça ao usuário para copiar ~/.gmail-mcp/gcp-oauth.keys.json para o computador dele no mesmo caminho.
Execute npx @shinzolabs/gmail-mcp auth.
Uma janela do navegador será aberta, onde o usuário pode selecionar um perfil, revisar os escopos solicitados e aprovar.
(Opcional) Para instalação em servidor remoto, anote o caminho do arquivo mencionado na mensagem de sucesso (~/.gmail-mcp/credentials.json por padrão). O REFRESH_TOKEN do usuário será encontrado aqui.

Configuração do Cliente

Existem várias opções para configurar seu cliente MCP com o servidor. Para configuração hospedada/remota, use a CLI do Smithery com uma Chave de API do Smithery. Para instalação local, use npx ou compile a partir do código-fonte. Cada uma dessas opções é explicada abaixo.

Servidor Remoto Smithery (Recomendado)

Para adicionar um servidor remoto ao seu cliente MCP config.json, execute o seguinte comando na CLI do Smithery:

npx -y @smithery/cli install @shinzo-labs/gmail-mcp

Digite seu CLIENT_ID, CLIENT_SECRET e REFRESH_TOKEN quando solicitado.

Smithery SDK

Se você está desenvolvendo sua própria aplicação de agente, pode usar o código boilerplate aqui.

Instalação Local via NPX

Para instalar o servidor localmente com npx, adicione o seguinte ao seu cliente MCP config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@shinzolabs/gmail-mcp"
      ]
    }
  }
}

Compilar a partir do Código-Fonte

Baixe o repositório:

git clone https://github.com/shinzo-labs/gmail-mcp.git

Instale os pacotes e compile com pnpm (dentro do repositório clonado):

pnpm i && pnpm build

Adicione o seguinte ao seu cliente MCP config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/path/to/gmail-mcp/dist/index.js"
      ]
    }
  }
}

Variáveis de Configuração

Variável	Descrição	Obrigatório?	Padrão
`AUTH_SERVER_PORT`	Porta para o servidor temporário de autenticação OAuth	Não	`3000`
`CLIENT_ID`	ID do cliente da API do Google (encontrado em `GMAIL_OAUTH_PATH`)	Sim, se houver conexão com servidor remoto	`''`
`CLIENT_SECRET`	Segredo do cliente da API do Google (encontrado em `GMAIL_OAUTH_PATH`)	Sim, se houver conexão com servidor remoto	`''`
`GMAIL_CREDENTIALS_PATH`	Caminho para o arquivo de credenciais do usuário	Não	`MCP_CONFIG_DIR/credentials.json`
`GMAIL_OAUTH_PATH`	Caminho para o arquivo do Cliente da API do Google	Não	`MCP_CONFIG_DIR/gcp-oauth.keys.json`
`MCP_CONFIG_DIR`	Diretório para armazenar arquivos de configuração	Não	`~/.gmail-mcp`
`REFRESH_TOKEN`	Token de atualização OAuth (encontrado em `GMAIL_CREDENTIALS_PATH`)	Sim, se houver conexão com servidor remoto	`''`
`PORT`	Porta para o método de transporte HTTP Streamable	Não	`3000`
`TELEMETRY_ENABLED`	Ativar telemetria	Não	`true`

Endpoints Suportados

Gerenciamento de Usuário

get_profile: Obter o perfil Gmail do usuário atual
stop_mail_watch: Parar de receber notificações push
watch_mailbox: Configurar notificações push para alterações na caixa de entrada

Gerenciamento de Mensagens

Gerenciando Mensagens

list_messages: Listar mensagens com filtragem opcional
get_message: Obter uma mensagem específica
get_attachment: Obter um anexo de mensagem
modify_message: Modificar rótulos de mensagem
send_message: Enviar uma mensagem de e-mail para destinatários especificados
delete_message: Excluir permanentemente uma mensagem
trash_message: Mover mensagem para a lixeira
untrash_message: Remover mensagem da lixeira
batch_modify_messages: Modificar várias mensagens
batch_delete_messages: Excluir várias mensagens

Gerenciamento de Rótulos

list_labels: Listar todos os rótulos
get_label: Obter um rótulo específico
create_label: Criar um novo rótulo
update_label: Atualizar um rótulo
patch_label: Atualização parcial de um rótulo
delete_label: Excluir um rótulo

Gerenciamento de Conversas

list_threads: Listar conversas de e-mail
get_thread: Obter uma conversa específica
modify_thread: Modificar rótulos de conversa
trash_thread: Mover conversa para a lixeira
untrash_thread: Remover conversa da lixeira
delete_thread: Excluir uma conversa

Gerenciamento de Rascunhos

list_drafts: Listar rascunhos na caixa de entrada do usuário
get_draft: Obter um rascunho específico por ID
create_draft: Criar um rascunho de e-mail no Gmail
update_draft: Substituir o conteúdo de um rascunho
delete_draft: Excluir um rascunho
send_draft: Enviar um rascunho existente

Gerenciamento de Configurações

Encaminhamento Automático

get_auto_forwarding: Obter configurações de encaminhamento automático
update_auto_forwarding: Atualizar configurações de encaminhamento automático

Configurações de IMAP

get_imap: Obter configurações de IMAP
update_imap: Atualizar configurações de IMAP

Configurações de POP

get_pop: Obter configurações de POP
update_pop: Atualizar configurações de POP

Respondedor de Férias

get_vacation: Obter configurações do respondedor de férias
update_vacation: Atualizar o respondedor de férias

Configurações de Idioma

get_language: Obter configurações de idioma
update_language: Atualizar configurações de idioma

Delegados

list_delegates: Listar delegados da conta
get_delegate: Obter um delegado específico
add_delegate: Adicionar um delegado
remove_delegate: Remover um delegado

Filtros

list_filters: Listar filtros de e-mail
get_filter: Obter um filtro específico
create_filter: Criar um novo filtro
delete_filter: Excluir um filtro

Endereços de Encaminhamento

list_forwarding_addresses: Listar endereços de encaminhamento
get_forwarding_address: Obter um endereço de encaminhamento específico
create_forwarding_address: Criar um endereço de encaminhamento
delete_forwarding_address: Excluir um endereço de encaminhamento

Configurações de Send-As

list_send_as: Listar aliases send-as
get_send_as: Obter um alias send-as específico
create_send_as: Criar um alias send-as
update_send_as: Atualizar um alias send-as
patch_send_as: Atualização parcial de um alias send-as
verify_send_as: Enviar e-mail de verificação
delete_send_as: Excluir um alias send-as

Configurações de S/MIME

list_smime_info: Listar configurações de S/MIME
get_smime_info: Obter uma configuração de S/MIME específica
insert_smime_info: Enviar uma nova configuração de S/MIME
set_default_smime_info: Definir configuração padrão de S/MIME
delete_smime_info: Excluir uma configuração de S/MIME

Contribuição

Contribuições são bem-vindas e incentivadas! Leia o CONTRIBUTING.md para obter diretrizes sobre problemas, contribuições e informações de contato.

Coleta de Dados e Privacidade

A Shinzo Labs coleta telemetria anônima limitada deste servidor para ajudar a melhorar nossos produtos e serviços. Nenhuma informação pessoalmente identificável é coletada como parte desse processo. Consulte a Política de Privacidade para obter mais detalhes sobre os tipos de dados coletados e como optar por não participar dessa telemetria.

Licença

MIT