MCP Google Calendar Plus

Um servidor para gerenciamento completo do Google Agenda, incluindo criação, atualização e exclusão de eventos. Requer autenticação Google 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 Calendar, Contacts 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 Calendar, Contacts e Gmail com autenticação OAuth2.

Por que Este Servidor MCP?

Outros servidores MCP de calendário 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 Calendário

  • ✅ Criar novos eventos de calendário
  • ✅ Atualizar eventos existentes (incluindo eventos recorrentes)
  • ✅ Excluir eventos
  • ✅ Gerenciar múltiplos calendários
  • ✅ Verificar disponibilidade entre calendários

Gerenciamento de Contatos

  • ✅ Listar e pesquisar contatos
  • ✅ Criar novos contatos com detalhes completos
  • ✅ Atualizar contatos existentes
  • ✅ Excluir contatos
  • ✅ Gerenciar detalhes de contato (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 marcadores e pastas
  • ✅ Atualizar status de e-mail (lido/não lido, com estrela, importante)
  • ✅ Criar e gerenciar rascunhos
  • ✅ Operações em lote para gerenciamento de e-mails em massa

Recursos

Recursos de Calendário

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

Recursos de Contatos

  • Pesquisa de Contatos: Pesquise contatos por nome, e-mail ou outros critérios
  • Detalhes Completos de Contato: 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 de 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 Marcadores: Crie e gerencie marcadores/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 por 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 de autenticação único para acesso a Calendar, Contacts 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á em "APIs e Serviços" > "Tela de consentimento OAuth"
    • 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 (necessário enquanto estiver em modo de teste)
  5. Crie as credenciais OAuth 2.0:
    • Vá em "APIs e Serviços" > "Credenciais"
    • Clique em "Criar Credenciais" > "ID do cliente OAuth"
    • Escolha "Aplicativo de desktop" 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 do 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 arquivo JSON baixado do Google Cloud Console.

3. Autenticação

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

Observação: Se você estiver atualizando de uma versão anterior, será necessário 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 Calendário

list-calendars

Liste todos os calendários acessíveis com suas propriedades.

list-events

Liste eventos de um ou mais calendários com opções de filtragem.

create-event

Crie um novo evento de calendário 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 individuais de eventos recorrentes
  • Alteração de detalhes do evento
  • Gerenciamento de participantes

delete-event

Exclua eventos de calendários.

search-events

Pesquise eventos em calendários usando consultas de texto.

get-freebusy

Consulte informações de disponibilidade em múltiplos calendários.

list-colors

Liste as cores disponíveis para eventos de calendário.

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 Contacts.

Ferramentas de 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 do e-mail (marcadores, status de leitura, estrela, arquivamento).

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 marcadores/pastas do Gmail.

create-label

Crie novos marcadores para organizar e-mails.

update-label

Modifique propriedades e cores dos marcadores.

delete-label

Remova marcadores do Gmail.

batch-update-emails

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

Exemplos de Uso

Exemplos de Calendário

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 de 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 marcadores

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 corresponde 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 "Aplicativo de desktop"
  • Se estiver atualizando de uma versão somente-calendário, 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 Calendar, Contacts e Gmail
  • Verifique se a conta do Google tem acesso aos recursos que você está tentando acessar
  • Certifique-se de que todas as APIs necessárias estejam ativadas no seu projeto do 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 em controle de versão
  • Use variáveis de ambiente para configurações sensíveis

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, de nspady.

Licença

MIT

Contribuições

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)
  • Expressão regular de validação de datetime melhorada 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
  • Interface profissional que identifica claramente esta como autenticação do Google Calendar
  • Nota de segurança adicionada informando que as credenciais nunca são armazenadas

v1.1.1

  • Documentação aprimorada para destacar as capacidades exclusivas de gerenciamento completo de calendário
  • Seção "Por que Este Servidor MCP?" adicionada com ênfase nos recursos de criar/atualizar/excluir
  • Descrição e palavras-chave do pacote 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 aplicativo de desktop
  • 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 queda de conexão
  • 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 calendário
  • Suporte a múltiplos calendários
  • Consultas de disponibilidade