Google MCP Tools

Integre serviços do Google como Gmail, Calendário, Drive e Tarefas com MCP.

Documentação

Google MCP Tools

Esta é uma coleção de ferramentas nativas do Google (ex.: Gmail, Agenda) para o protocolo MCP, projetada para integrar-se perfeitamente a clientes de IA como Claude ou Cursor.

Instalação Rápida

Clique abaixo para instalação com um clique com .mcpb:

JSON configs

{
  "mcpServers": {
    "google-mcp": {
      "command": "bunx",
      "args": ["--no-cache", "google-mcp@latest"],
      "env": {
        // Either can be used, but not both
        // Use OAuth
        "GOOGLE_OAUTH_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "GOOGLE_OAUTH_TOKEN_PATH": "<PATH_TO_STORE_TOKENS> CAN_BE_ANYWHERE_ON_YOUR_SYSTEM",
        // Use Service Account
        "GOOGLE_CLIENT_EMAIL": "<YOUR_SERVICE_ACCOUNT_EMAIL>",
        "GOOGLE_PRIVATE_KEY": "<YOUR_SERVICE_ACCOUNT_PRIVATE_KEY>",
        "GMAIL_USER_TO_IMPERSONATE": "<USER_TO_IMPERSONATE>"
      }
    }
  }
}

Novidades na v1.1.0

🆕 Principais Recursos

Suporte Completo a Anexos de E-mail:
- ✉️ Envie e-mails com anexos de arquivos locais ou do Google Drive
- 📥 Baixe todos os anexos de e-mail para o armazenamento local
- 🔄 Fontes duplas de anexos: Caminhos de arquivos locais ou IDs de arquivos do Google Drive
- 📁 Manipulação inteligente de arquivos: Detecção automática de tipo MIME e sanitização de nomes de arquivo

🔧 Capacidades Aprimoradas de E-mail

Anexos de múltiplas fontes: Anexe arquivos do armazenamento local ou do Google Drive no mesmo e-mail
Nomes de arquivo personalizados: Substitua os nomes de arquivo originais dos anexos
Validação de tamanho de arquivo: Aplicação automática do limite de 25MB do Gmail
Downloads multiplataforma: Detecção automática da pasta de Downloads no Windows, macOS e Linux
Resolução de conflitos: Renomeação automática de arquivos para evitar sobrescritas

📁 Ferramentas Novas e Aprimoradas

google_gmail_send_email: Agora suporta anexos de arquivos locais e do Google Drive
google_gmail_draft_email: Crie rascunhos com anexos
google_gmail_download_attachments: Baixe todos os anexos de e-mail com caminho personalizável

Recursos

Gerenciamento de OAuth:
- Atualize automaticamente tokens de acesso expirados
- Atualize tokens no arquivo de token sem reautenticação
- Reautenticação completa com limpeza automatizada de tokens
- Mantenha a continuidade da sessão em operações de longa duração
Gmail:
- Envie e-mails com múltiplos destinatários (para, cc, bcc) e anexos de arquivos locais ou do Google Drive.
- Baixe todos os anexos de e-mail para o armazenamento local com suporte multiplataforma.
- Liste e-mails com consultas personalizadas, rótulos e limites de resultados.
- Leia e-mails específicos por ID com informações de anexos.
- Gerencie rótulos (adicionar, remover, listar).
- Rascunhe e exclua e-mails.
Agenda:
- Liste calendários e defina um calendário padrão.
- Crie eventos com detalhes (resumo, horário de início/fim, participantes, etc.).
- Liste eventos futuros com filtros personalizáveis.
- Atualize ou exclua eventos existentes.
- Encontre intervalos de tempo livres para agendamento.
Drive:
- Filtre com consultas de pesquisa
- Ordene por data de modificação ou outros critérios
- Personalize a quantidade exibida
- Veja metadados detalhados de arquivos
- Leia o conteúdo de arquivos (texto, documentos, planilhas)
- Crie novos arquivos com conteúdo especificado
- Atualize arquivos existentes
- Exclua arquivos (lixeira ou permanentemente)
- Compartilhe arquivos com permissões específicas
Tarefas:
- Veja todas as listas de tarefas
- Crie novas listas de tarefas
- Exclua listas de tarefas existentes
- Defina a lista de tarefas padrão
- Liste tarefas com filtros
- Veja detalhes de tarefas
- Crie tarefas com título, notas e datas de vencimento
- Atualize propriedades de tarefas
- Marque tarefas como concluídas
- Exclua tarefas
Planos TODO:
- Google Contatos: Pesquise e gerencie contatos.
- E muito mais...

Você pode encadear comandos para fluxos de trabalho, por exemplo:

"Liste meus e-mails não lidos, rascunhe uma resposta para o mais recente e agende uma reunião de acompanhamento amanhã às 14h."

Implantação Hospedada

Uma implantação hospedada está disponível em Fronteir AI.

Gerenciamento de Token OAuth

O servidor inclui gerenciamento de token OAuth integrado para lidar com tokens de acesso expirados de forma elegante:

Atualização Automática de Token: Quando os tokens de acesso expiram, você pode atualizá-los sem passar pelo fluxo OAuth completo novamente
Reautenticação Completa: Lida automaticamente com casos em que os tokens de atualização são inválidos ou expirados
Armazenamento Persistente: Tokens atualizados são salvos automaticamente no caminho do arquivo de token configurado
Continuidade de Sessão: Todos os serviços do Google são reinicializados com tokens novos após a atualização

Atualizando Tokens

Se você encontrar erros de autenticação ou quiser atualizar proativamente seus tokens, basta pedir:

Refresh my Google OAuth tokens

Isso irá:

Usar seu token de atualização armazenado para obter novos tokens de acesso
Atualizar o arquivo de token com as novas credenciais
Reinicializar todos os serviços do Google com autenticação nova
Mostrar o novo tempo de expiração do token

Reautenticação Completa

Se você receber erros de invalid_grant ou seu token de atualização expirou, você pode começar do zero:

Re-authenticate my Google account

Este processo automatizado irá:

Excluir tokens existentes do seu arquivo de token
Iniciar o servidor OAuth para lidar com o callback
Abrir o navegador para autenticação nova
Salvar novos tokens automaticamente
Reinicializar serviços com credenciais novas

Você só precisará clicar em "Permitir" no navegador - todo o resto é automatizado!

Nota: Se você não tiver um token de atualização válido, precisará passar pelo fluxo de autenticação OAuth inicial novamente.

Instalação Manual

Pré-requisitos:

Instale o Bun:

brew install oven-sh/bun/bun  # macOS/Linux with Homebrew

Configure o OAuth:
- Crie um projeto no Google Cloud no Console do Google Cloud.
- Configure as credenciais OAuth 2.0 (ID do cliente, Segredo do cliente).
- Escolha o tipo Aplicativo de desktop.
- Se estiver usando o modo de teste, adicione seu e-mail à lista de usuários de teste.
- Certifique-se de habilitar o acesso à API para os serviços desejados (Gmail, Agenda, Drive etc.).
Configure seu cliente: Edite seu claude_desktop_config.json (ou arquivo de configuração equivalente para seu cliente):

{
  "mcpServers": {
    "google-mcp": {
      "command": "bunx",
      "args": ["--no-cache", "google-mcp@latest"],
      "env": {
        // Either can be used, but not both
        // Use OAuth
        "GOOGLE_OAUTH_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "GOOGLE_OAUTH_TOKEN_PATH": "<PATH_TO_STORE_TOKENS>",
        // Use Service Account
        "GOOGLE_CLIENT_EMAIL": "<YOUR_SERVICE_ACCOUNT_EMAIL>",
        "GOOGLE_PRIVATE_KEY": "<YOUR_SERVICE_ACCOUNT_PRIVATE_KEY>",
        "GMAIL_USER_TO_IMPERSONATE": "<USER_TO_IMPERSONATE>"
      }
    }
  }
}

Autentique:
- Na primeira vez que você executar o servidor, ele abrirá um navegador para autenticação OAuth. Siga as instruções para conceder acesso, e os tokens serão salvos em GOOGLE_OAUTH_TOKEN_PATH.

Uso

Agora, peça ao Claude para usar a ferramenta google-mcp.

Send an email to jane.doe@example.com with the subject "Meeting Notes" and body "Here are the notes from today."

List my upcoming calendar events for the next 3 days.

Create a calendar event titled "Team Sync" tomorrow at 10 AM for 1 hour.

Refresh my Google OAuth tokens

Re-authenticate my Google account

Suporte a Transporte

Este servidor MCP suporta transportes stdio e HTTP via variáveis de ambiente:

Transporte Stdio (Padrão)

# Default mode - uses stdio transport
bun run dev
# Or explicitly
MCP_TRANSPORT=stdio bun run index.ts

Transporte HTTP (HTTP Transmissível)

# HTTP mode with Streamable HTTP support
MCP_TRANSPORT=http bun run index.ts
# Or with custom port
MCP_TRANSPORT=http PORT=3000 bun run index.ts

Quando executado em modo HTTP, o servidor fornece estes endpoints:

GET /health - Endpoint de verificação de saúde com contagem de sessões
GET /mcp - Informações de sessão e status do servidor
POST /mcp - Endpoint principal MCP JSON-RPC para envio de solicitações
DELETE /mcp - Endpoint de encerramento de sessão

Gerenciamento de Sessão

O transporte HTTP Transmissível usa o SDK MCP oficial com gerenciamento automático de sessão:

Sessões Automáticas: O servidor gera automaticamente IDs de sessão seguros
Streaming SSE: Suporta Server-Sent Events para comunicação em tempo real
Respostas JSON: Reverte para respostas JSON quando SSE não está disponível
Proteção DNS: Recursos de segurança integrados para implantação em produção

Configuração para Transporte HTTP

Para transporte HTTP, configure seu cliente com a URL do servidor:

{
  "mcpServers": {
    "google-mcp-http": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Desenvolvimento Local

git clone https://github.com/vakharwalad23/google-mcp.git
cd google-mcp
bun install

# Run in stdio mode (default)
bun run dev:stdio

# Run in HTTP mode
bun run dev:http

Obrigado por usar o Google MCP Tools! Se você tiver alguma dúvida ou sugestão, sinta-se à vontade para abrir uma issue ou contribuir com o projeto.

Divirta-se com as ferramentas e aproveite!!