Servidor MCP Headless Gmail | Awesome MCP Servers

MCP Headless Gmail Server (NPM & Docker)

Um servidor MCP (Model Context Protocol) que fornece acesso para obter e enviar e-mails do Gmail sem necessidade de configuração local de credenciais ou tokens.

Por que o MCP Headless Gmail Server?

Vantagens Críticas

Operação Headless e Remota: Diferente de outras soluções MCP para Gmail que exigem execução fora do Docker e acesso a arquivos locais, este servidor pode operar completamente headless em ambientes remotos, sem navegador e sem acesso a arquivos locais.
Arquitetura Desacoplada: Qualquer cliente pode concluir o fluxo OAuth de forma independente e, em seguida, passar as credenciais como contexto para este servidor MCP, criando uma separação completa entre o armazenamento de credenciais e a implementação do servidor.

Vantagens Adicionais (não críticas)

Funcionalidade Focada: Em muitos casos de uso, especialmente em aplicações de marketing, apenas o acesso ao Gmail é necessário, sem serviços adicionais do Google como o Calendar, tornando esta implementação focada ideal.
Pronto para Docker: Projetado com containerização em mente para uma configuração bem isolada, independente de ambiente e com um clique.
Dependências Confiáveis: Construído sobre a biblioteca bem mantida google-api-python-client.

Recursos

Obter os e-mails mais recentes do Gmail com os primeiros 1.000 caracteres do corpo
Obter o conteúdo completo do corpo do e-mail em blocos de 1k usando o parâmetro de deslocamento (offset)
Enviar e-mails através do Gmail
Atualizar tokens de acesso separadamente
Tratamento automático de renovação de tokens

Pré-requisitos

Python 3.10 ou superior
Credenciais da API do Google (client ID, client secret, access token e refresh token)

Instalação

# Clone the repository
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail

# Install dependencies
pip install -e .

Docker

Construindo a Imagem Docker

# Build the Docker image
docker build -t mcp-headless-gmail .

Uso com Claude Desktop

Você pode configurar o Claude Desktop para usar a imagem Docker adicionando o seguinte à sua configuração do Claude:

docker

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

versão npm

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

Observação: Com esta configuração, você precisará fornecer suas credenciais da API do Google nas chamadas de ferramenta, conforme mostrado na seção Usando as Ferramentas. As credenciais do Gmail não são passadas como variáveis de ambiente para manter a separação entre o armazenamento de credenciais e a implementação do servidor.

Publicação Multiplataforma

Para publicar a imagem Docker para múltiplas plataformas, você pode usar o comando docker buildx. Siga estes passos:

Crie uma nova instância de builder (se ainda não tiver):
```
docker buildx create --use
```

Construa e envie a imagem para múltiplas plataformas:

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .

Verifique se a imagem está disponível para as plataformas especificadas:
```
docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest
```

Uso

O servidor fornece funcionalidade do Gmail através de ferramentas MCP. O tratamento de autenticação é simplificado com uma ferramenta dedicada de renovação de tokens.

Iniciando o Servidor

mcp-server-headless-gmail

Usando as Ferramentas

Ao usar um cliente MCP como o Claude, você tem duas maneiras principais de lidar com a autenticação:

Renovando Tokens (Primeiro Passo ou Quando os Tokens Expirarem)

Se você tiver tanto o access token quanto o refresh token:

{
  "google_access_token": "your_access_token",
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

Se o seu access token expirou, você pode renová-lo apenas com o refresh token:

{
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

Isso retornará um novo access token e seu tempo de expiração, que você pode usar para chamadas subsequentes.

Obtendo E-mails Recentes

Recupera e-mails recentes com os primeiros 1.000 caracteres do corpo de cada e-mail:

{
  "google_access_token": "your_access_token",
  "max_results": 5,
  "unread_only": false
}

A resposta inclui:

Metadados do e-mail (id, threadId, de, para, assunto, data, etc.)
Primeiros 1000 caracteres do corpo do e-mail
body_size_bytes: Tamanho total do corpo do e-mail em bytes
contains_full_body: Booleano indicando se o corpo inteiro está incluído (true) ou truncado (false)

Obtendo o Conteúdo Completo do Corpo do E-mail

Para e-mails com corpos maiores que 1.000 caracteres, você pode recuperar o conteúdo completo em blocos:

{
  "google_access_token": "your_access_token",
  "message_id": "message_id_from_get_recent_emails",
  "offset": 0
}

Você também pode obter o conteúdo do e-mail pelo ID da thread:

{
  "google_access_token": "your_access_token",
  "thread_id": "thread_id_from_get_recent_emails",
  "offset": 1000
}

A resposta inclui:

Um bloco de 1k do corpo do e-mail começando no deslocamento especificado
body_size_bytes: Tamanho total do corpo do e-mail
chunk_size: Tamanho do bloco retornado
contains_full_body: Booleano indicando se o bloco contém o restante do corpo

Para recuperar o corpo inteiro de uma mensagem longa, faça chamadas sequenciais aumentando o deslocamento em 1000 a cada vez até que contains_full_body seja true.

Enviando um E-mail

{
  "google_access_token": "your_access_token",
  "to": "recipient@example.com",
  "subject": "Hello from MCP Gmail",
  "body": "This is a test email sent via MCP Gmail server",
  "html_body": "<p>This is a <strong>test email</strong> sent via MCP Gmail server</p>"
}

Fluxo de Renovação de Tokens

Comece chamando a ferramenta gmail_refresh_token com:
- Suas credenciais completas (access token, refresh token, client ID e client secret), ou
- Apenas seu refresh token, client ID e client secret se o access token expirou
Use o novo access token retornado para chamadas subsequentes da API.
Se você receber uma resposta indicando expiração do token, chame a ferramenta gmail_refresh_token novamente para obter um novo token.

Essa abordagem simplifica a maioria das chamadas de API, não exigindo credenciais de cliente para cada operação, enquanto ainda permite a renovação de tokens quando necessário.

Obtendo Credenciais da API do Google

Para obter as credenciais necessárias da API do Google, siga estes passos:

Acesse o Google Cloud Console
Crie um novo projeto
Ative a API do Gmail
Configure a tela de consentimento OAuth
Crie credenciais de client ID OAuth (selecione "Aplicativo de desktop" como tipo de aplicativo)
Salve o client ID e o client secret
Use OAuth 2.0 para obter access tokens e refresh tokens com os seguintes escopos:
- https://www.googleapis.com/auth/gmail.readonly (para leitura de e-mails)
- https://www.googleapis.com/auth/gmail.send (para envio de e-mails)

Renovação de Tokens

Este servidor implementa renovação automática de tokens. Quando seu access token expira, o cliente da API do Google usará o refresh token, o client ID e o client secret para obter um novo access token sem exigir intervenção do usuário.

Nota de Segurança

Este servidor requer acesso direto às suas credenciais da API do Google. Sempre mantenha seus tokens e credenciais seguros e nunca os compartilhe com partes não confiáveis.

Licença

Consulte o arquivo LICENSE para obter detalhes.

MCP Headless Gmail Server

Documentação