MCP Google Workspace

Um servidor MCP abrangente para gerenciar serviços do Google Workspace como Calendário, Contatos e Gmail usando autenticação OAuth2.

GitHub

Documentação

MCP Google Workspace

O ÚNICO servidor MCP abrangente para Google Workspace que permite que Claude, Cursor, Windsurf e outros sistemas de IA gerenciem completamente Google Agenda, Contatos E Gmail - leia, crie, atualize, exclua e organize em todos os três serviços!

Integração completa com Google Workspace para Claude Desktop e outros agentes de IA usando o Model Context Protocol (MCP). Este servidor fornece capacidades abrangentes de gerenciamento para Agenda, Contatos e Gmail com autenticação OAuth2.

Por que Este Servidor MCP?

Outros servidores MCP de agenda fornecem apenas acesso somente leitura. Este é o único servidor MCP que dá a sistemas de IA como Claude, Cursor e Windsurf a capacidade de:

Gerenciamento de Agenda

  • ✅ Criar novos eventos de agenda
  • ✅ Atualizar eventos existentes (incluindo eventos recorrentes)
  • ✅ Excluir eventos
  • ✅ Gerenciar múltiplas agendas
  • ✅ Verificar disponibilidade entre agendas

Gerenciamento de Contatos

  • ✅ Listar e pesquisar contatos
  • ✅ Criar novos contatos com detalhes completos
  • ✅ Atualizar contatos existentes
  • ✅ Excluir contatos
  • ✅ Gerenciar detalhes de contatos (e-mails, telefones, endereços, organizações)

Gerenciamento de Gmail (NOVO!)

  • ✅ Pesquisar e listar e-mails com consultas poderosas
  • ✅ Ler conteúdo completo de e-mails com anexos
  • ✅ Enviar novos e-mails e respostas
  • ✅ Organizar com rótulos e pastas
  • ✅ Atualizar status de e-mails (lido/não lido, estrelado, importante)
  • ✅ Criar e gerenciar rascunhos
  • ✅ Operações em lote para gerenciamento de e-mails em massa

Recursos

Recursos da Agenda

  • Suporte a Múltiplas Agendas: Liste eventos de várias agendas simultaneamente
  • Gerenciamento de Eventos: Crie, atualize (incluindo notificações), exclua e pesquise eventos de agenda
  • Eventos Recorrentes: Escopos avançados de modificação para eventos recorrentes (instância única, todas as instâncias ou apenas instâncias futuras)
  • Gerenciamento de Agenda: Liste agendas e suas propriedades
  • Consultas de Disponibilidade: Verifique disponibilidade entre agendas

Recursos de Contatos

  • Pesquisa de Contatos: Pesquise contatos por nome, e-mail ou outros critérios
  • Detalhes Completos de Contatos: Gerencie nomes, e-mails, números de telefone, endereços, organizações e notas
  • Operações em Lote: Liste contatos com suporte a paginação
  • Seleção de Campos: Escolha quais campos de contato recuperar para respostas otimizadas

Recursos do Gmail (NOVO!)

  • Pesquisa Avançada: Use os poderosos operadores de pesquisa do Gmail
  • Gerenciamento de E-mails: Leia, envie, responda, encaminhe e exclua e-mails
  • Organização por Rótulos: Crie e gerencie rótulos/pastas
  • Gerenciamento de Rascunhos: Crie, atualize e envie rascunhos
  • Operações em Lote: Atualize vários e-mails de uma vez
  • Suporte a Tópicos: Lide com conversas de e-mail
  • Informações de Anexos: Visualize detalhes de anexos (nomes, tamanhos, tipos)

Autenticação

  • Autenticação OAuth2: Autenticação segura com renovação automática de token
  • Permissões Unificadas: Fluxo único de autenticação para acesso a Agenda, Contatos e Gmail

Instalação

Via npx (Recomendado)

npx mcp-google

Via npm

npm install -g mcp-google

Configuração

1. Crie Credenciais OAuth do Google

  1. Acesse o Google Cloud Console
  2. Crie um novo projeto ou selecione um existente
  3. Ative estas APIs:
  4. Configure a tela de consentimento OAuth:
    • Vá para "APIs & Services" > "OAuth consent screen"
    • Escolha o tipo de usuário "Externo"
    • Preencha os campos obrigatórios (nome do aplicativo, e-mail de suporte, etc.)
    • Adicione seu e-mail como usuário de teste (obrigatório enquanto estiver em modo de teste)
  5. Crie credenciais OAuth 2.0:
    • Vá para "APIs & Services" > "Credentials"
    • Clique em "Create Credentials" > "OAuth client ID"
    • Escolha "Desktop app" como tipo de aplicativo
    • Dê um nome ao seu cliente OAuth (ex.: "MCP Calendar Client")
    • Baixe o arquivo JSON de credenciais

2. Configure o Claude Desktop

Adicione isto ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Opção A: Variáveis de Ambiente Diretas (Mais Simples - Sem necessidade de arquivo JSON!)

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Opção B: Use o Arquivo de Credenciais Google Baixado

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/downloaded/credentials.json"
      }
    }
  }
}

Basta usar o caminho do arquivo onde você salvou o JSON baixado do Google Cloud Console.

3. Autentique

  1. Reinicie o Claude Desktop
  2. O servidor MCP abrirá uma janela do navegador para autenticação
  3. Faça login com sua conta Google e conceda permissões de Agenda, Contatos E Gmail
  4. Os tokens serão salvos com segurança para uso futuro

Nota: Se estiver atualizando de uma versão anterior, você precisará reautenticar para conceder as novas permissões do Gmail.

Variáveis de Ambiente

  • GOOGLE_OAUTH_CREDENTIALS: Caminho para o arquivo JSON de credenciais OAuth
  • GOOGLE_CALENDAR_MCP_TOKEN_PATH: Caminho personalizado para armazenamento de tokens (opcional)
  • NODE_ENV: Defina como "production" para uso em produção

Ferramentas Disponíveis

Ferramentas de Agenda

list-calendars

Liste todas as agendas acessíveis com suas propriedades.

list-events

Liste eventos de uma ou mais agendas com opções de filtragem.

create-event

Crie um novo evento de agenda com suporte para:

  • Eventos únicos ou recorrentes
  • Participantes e notificações
  • Cores personalizadas
  • Fusos horários

update-event

Atualize eventos existentes incluindo:

  • Modificação de instâncias únicas de eventos recorrentes
  • Alteração de detalhes do evento
  • Gerenciamento de participantes

delete-event

Exclua eventos de agendas.

search-events

Pesquise eventos entre agendas usando consultas de texto.

get-freebusy

Consulte informações de disponibilidade em múltiplas agendas.

list-colors

Liste as cores disponíveis para eventos de agenda.

Ferramentas de Contatos

list-contacts

Liste e pesquise contatos com suporte a paginação.

get-contact

Obtenha informações detalhadas sobre um contato específico.

create-contact

Crie novos contatos com:

  • Nomes e apelidos
  • Múltiplos endereços de e-mail
  • Números de telefone
  • Endereços físicos
  • Organizações e cargos
  • Notas e biografias

update-contact

Atualize informações de contatos existentes com atualizações específicas por campo.

delete-contact

Exclua contatos do Google Contatos.

Ferramentas do Gmail (NOVO!)

list-emails

Pesquise e liste e-mails com consultas poderosas do Gmail.

get-email

Leia o conteúdo completo do e-mail incluindo corpo e anexos.

send-email

Envie novos e-mails ou respostas com suporte a HTML.

update-email

Modifique propriedades de e-mails (rótulos, status de leitura, estrela, arquivar).

delete-email

Mova e-mails para a lixeira ou exclua permanentemente.

create-draft

Crie rascunhos de e-mail para edição posterior.

update-draft

Edite rascunhos de e-mail existentes.

send-draft

Envie um rascunho salvo.

list-labels

Liste todos os rótulos/pastas do Gmail.

create-label

Crie novos rótulos para organizar e-mails.

update-label

Modifique propriedades e cores de rótulos.

delete-label

Remova rótulos do Gmail.

batch-update-emails

Execute operações em massa em múltiplos e-mails.

Exemplos de Uso

Exemplos de Agenda

Verificar disponibilidade

What times am I free tomorrow between 9am and 5pm?

Criar um evento

Create a meeting called "Team Standup" tomorrow at 10am for 30 minutes

Pesquisar eventos

Find all events this week that mention "project review"

Atualizar eventos recorrentes

Change all future instances of my weekly team meeting to 2pm

Exemplos de Contatos

Listar contatos

Show me all my contacts with email addresses

Criar um contato

Create a contact for John Doe, email: john@example.com, phone: 555-1234

Pesquisar contatos

Find contacts who work at Google

Atualizar contato

Update Jane Smith's phone number to 555-5678

Exemplos do Gmail

Pesquisar e-mails

Show me all unread emails from this week

Enviar e-mail

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 2pm"

Organizar caixa de entrada

Mark all newsletters as read and archive them

Gerenciar rótulos

Create a label called "Important Projects" and apply it to all emails from my manager

Operações em lote

Move all emails older than 30 days to trash

Solução de Problemas

Problemas de Autenticação

  • Certifique-se de que o URI de redirecionamento corresponda exatamente: http://localhost:3000/oauth2callback
  • Verifique se tanto a Calendar API quanto a People API estão ativadas no Google Cloud Console
  • Confirme que as credenciais OAuth são do tipo "Desktop app"
  • Se estiver atualizando de uma versão somente agenda, execute novamente a autenticação para conceder permissões de contatos

Expiração de Token

  • Os tokens são renovados automaticamente
  • Se os problemas persistirem, exclua o arquivo de token e reautentique

Erros de Permissão

  • Certifique-se de ter concedido todas as permissões solicitadas de Agenda, Contatos e Gmail
  • Verifique se a conta Google tem acesso aos recursos que você está tentando acessar
  • Certifique-se de que todas as APIs necessárias estejam ativadas no seu projeto Google Cloud:
    • Google Calendar API
    • Google People API
    • Gmail API

Segurança

  • Os tokens OAuth são armazenados com permissões restritas (0600)
  • Segredos do cliente nunca devem ser commitados no controle de versão
  • Use variáveis de ambiente para configuração sensível

Desenvolvimento

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

Equipe

Desenvolvido por Boris Djordjevic e pela equipe 199 Longevity.

Construído sobre o google-calendar-mcp original por nspady.

Licença

MIT

Contribuição

Contribuições são bem-vindas! Abra uma issue ou envie um pull request no GitHub.

Histórico de Versões

v1.1.3

  • Corrigida a validação de fuso horário para suportar milissegundos em timestamps ISO
  • Agora compatível com o formato Date.toISOString() do JavaScript (ex.: 2024-01-01T00:00:00.000Z)
  • Regex de validação de data/hora melhorado para lidar com ambos os formatos, com e sem milissegundos

v1.1.2

  • Fluxo de autenticação melhorado com página de destino clara e informativa
  • Os usuários agora veem exatamente quais permissões o Claude terá antes de conectar
  • UI profissional que identifica claramente isso como autenticação do Google Agenda
  • Nota de segurança adicionada de que as credenciais nunca são armazenadas

v1.1.1

  • Documentação aprimorada para destacar capacidades únicas de gerenciamento completo de agenda
  • Seção "Por que Este Servidor MCP?" adicionada enfatizando recursos de criar/atualizar/excluir
  • Descrição do pacote e palavras-chave atualizadas para melhor descoberta

v1.1.0

  • Configuração simplificada: Suporte adicionado para variáveis de ambiente diretas (sem necessidade de arquivo JSON!)
  • Os usuários agora podem usar GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET diretamente na configuração do Claude
  • README atualizado com instruções mais claras de configuração OAuth para Desktop app
  • Etapas desnecessárias de configuração de URI de redirecionamento removidas

v1.0.1

  • Lógica de nova tentativa automática adicionada para erros de rede
  • Tratamento de erros melhorado para problemas de desconexão de socket
  • Recuperação silenciosa quando eventos são criados apesar de erros de conexão

v1.0.0

  • Lançamento inicial com autenticação OAuth2 aprimorada
  • Ferramentas abrangentes de gerenciamento de agenda
  • Suporte a múltiplas agendas
  • Consultas de disponibilidade