mcp-google-calendar

Google Calendar MCP

Português | Русский

A1 Google Calendar MCP permite que um aplicativo de IA gerencie o Google Agenda em linguagem natural. Revise sua semana, agende uma reunião com convidados e um link do Google Meet, remarcar ou cancelar, encontre um horário em que todos estejam livres e bloqueie Fora do Escritório ou Foco.

Ele usa a API do Google Agenda com sua conta Google. Ele distingue uma série recorrente inteira de uma ocorrência única e torna explícitos os limites da API do Agenda, em vez de sugerir que toda tarefa de agenda é possível.

• 19 ferramentas. Inspecione agendas, eventos e disponibilidade, crie e edite eventos, expanda séries recorrentes e bloqueie Fora do Escritório e Foco — além de seis para conectar sua conta Google.
• Entre na conversa. Nenhum arquivo de credenciais para escrever manualmente: peça ao assistente para conectar, aprove o acesso no navegador e a próxima solicitação funciona — sem reiniciar. O segredo do cliente viaja como um caminho de arquivo, nunca pela conversa.
• Ninguém recebe e-mail por acidente. O padrão da API do Agenda para convites, alterações e cancelamentos é o silêncio; os convidados recebem e-mail somente quando você solicitar via send_updates.
• As gravações nunca são repetidas. Após uma falha ambígua, o servidor não tenta novamente uma gravação — um evento duplicado poderia reenviar e-mail para todos os convidados.
• Escopos mínimos do Google. Ele usa calendar.events e calendar.readonly, sem o escopo amplo calendar.

Comece com uma pergunta somente leitura:

O que está na minha agenda esta semana? Aponte quaisquer reuniões sobrepostas.

Conecte o servidor · Explore casos de uso · Abra a documentação técnica

Veja funcionando em um minuto

Você: Como está minha quinta-feira e quando Anna e eu estamos livres?

Assistente: Mostra os eventos de quinta-feira e os horários livres que vocês compartilham. Nada muda.

Você: Agende uma revisão de design de 45 minutos com Anna no primeiro horário livre, com um link do Google Meet.

Assistente: Mostra o horário proposto, a lista de convidados e o link do Meet, e então pede confirmação antes de criar o evento.

Você: Confirmo.

Assistente: Cria o evento. Ninguém recebe e-mail, a menos que você peça para enviar convites.

Conteúdo

• Início rápido
• O que você pode pedir para fazer
• Como um evento muda
• O que pode mudar
• Obtendo acesso
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa do Node.js 20+, de uma conta Google e de credenciais OAuth de um projeto do Google Cloud com a API do Google Agenda ativada.

1. Prepare o acesso OAuth do Google.
2. Adicione o servidor ao seu aplicativo de IA.
3. Faça a pergunta somente leitura acima.

codex mcp add google-calendar \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  --transport stdio --scope user google-calendar \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

claude mcp list

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "mcpServers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "${input:calendar_client_id}",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "${input:calendar_client_secret}",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "${input:calendar_refresh_token}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "calendar_client_id", "description": "Google OAuth client ID" },
    { "type": "promptString", "id": "calendar_client_secret", "description": "Google OAuth client secret", "password": true },
    { "type": "promptString", "id": "calendar_refresh_token", "description": "Google OAuth refresh token", "password": true }
  ]
}

O que você pode pedir para fazer

Veja sua agenda

• Quais reuniões tenho esta semana? Inclua as recorrentes.
• Mostre o 1:1 de amanhã com seus convidados, link do Meet e lembretes.
• Liste todas as ocorrências da sincronização da equipe em março.

Planeje e altere reuniões

• Crie uma revisão de 45 minutos na quinta-feira com dois convidados e um link do Google Meet.
• Remarque a retrospectiva uma hora depois e atualize a lista de convidados — mas não envie e-mail para ninguém ainda.
• Mova o evento de planejamento para a agenda da equipe.
• Cancele a ocorrência de sexta-feira do standup, deixando o restante da série intacto.

Proteja seu tempo

• Quando Anna, Boris e eu estamos todos livres por uma hora na próxima semana?
• Bloqueie Fora do Escritório para minhas férias e recuse automaticamente novos convites.
• Crie duas horas de Foco amanhã de manhã e silencie o Google Chat.

Como um evento muda

1. calendar_id: "primary" é sua agenda principal; outras agendas vêm de list_calendars, e gravações precisam de acesso de escritor.
2. Uma série recorrente e uma ocorrência única têm ids diferentes: o id da série altera ou cancela todas as ocorrências, um id de instância (de list_event_instances) exatamente uma.
3. update_event altera apenas os campos que você fornece, mas um objeto aninhado substitui seu predecessor por completo — uma nova lista attendees substitui toda a lista de convidados.
4. Nenhuma gravação envia e-mail a ninguém, a menos que send_updates diga o contrário — o padrão da API do Agenda é o silêncio.

Blocos de Fora do Escritório e Foco existem apenas na agenda principal de uma conta do Google Workspace; Gmail de consumidor e agendas secundárias os rejeitam. Criar um evento não verifica conflitos — peça uma verificação de disponibilidade primeiro. Eventos de dia inteiro terminam em uma data exclusiva: um evento até sexta-feira termina na data de sábado.

O que pode mudar

O cliente de IA controla os prompts de confirmação. O servidor marca ferramentas de leitura, gravação e destrutivas para que o cliente possa distinguir uma inspeção de uma alteração ao vivo.

Obtendo acesso

O acesso às suas próprias agendas requer OAuth 2.0; uma chave de API não é suficiente. Há duas maneiras de conectar, e a primeira não precisa de nenhum arquivo de configuração.

Entre pela conversa

Inicie o servidor sem credenciais e peça ao assistente para conectar. Ele o guia com seis ferramentas integradas:

O login entra em vigor imediatamente: a próxima chamada de ferramenta funciona sem reiniciar o cliente de IA. O token é armazenado em ~/.config/mcp-google-calendar/credentials.json (no Windows, em %APPDATA%), legível apenas pela sua conta, e nunca sai da sua máquina.

Ou configure variáveis de ambiente

O caminho clássico, e o indicado para CI e instalações headless:

1. Crie ou selecione um projeto do Google Cloud e ative a API do Google Agenda.

2. Configure a tela de consentimento OAuth e crie um cliente OAuth de Aplicativo de desktop.

3. Autorize a conta Google cujas agendas você deseja gerenciar. O Playground OAuth 2.0 pode obter o token de atualização quando Usar minhas próprias credenciais OAuth estiver ativado.

4. Solicite ambos os escopos:

   https://www.googleapis.com/auth/calendar.events
   https://www.googleapis.com/auth/calendar.readonly
   

   O escopo amplo https://www.googleapis.com/auth/calendar é necessário apenas para chamadas raw_request que gerenciam agendas ou regras de compartilhamento.

Variáveis de ambiente sempre vencem um login feito na conversa, então uma instalação configurada existente continua se comportando exatamente como antes.

Tokens de atualização OAuth em modo de teste podem expirar após sete dias. Publique o aplicativo OAuth ou use um aplicativo Interno em um domínio do Workspace quando precisar de acesso de longa duração. Trate o segredo do cliente e o token de atualização como senhas.

Configuração

* Forneça o trio OAuth ou um token de acesso. Sem credenciais, o servidor ainda inicia e completa o handshake MCP; a primeira chamada de ferramenta então nomeia as variáveis exatas a definir.

Dados, limites e trabalho em segundo plano

• As solicitações vão para o Google Agenda. O servidor local atualiza os tokens OAuth do Google e chama a API do Agenda. Sua telemetria anônima contém um ID de instalação, versão do pacote, cliente de IA e versões de plataforma, e nomes de ferramentas — nunca tokens OAuth, dados de agenda, argumentos de ferramentas ou prompts. Defina ASKADS_TELEMETRY=0 para optar por não participar.
• O Google aplica cotas por projeto. Em 429, o servidor tenta novamente com backoff; leituras também tentam novamente após erros de rede e 5xx, enquanto gravações não são repetidas após uma falha incerta — um evento duplicado poderia reenviar e-mail para todos os convidados.
• Não há polling em segundo plano. O servidor executa apenas quando chamado. list_events suporta verificações incrementais via updated_min; se seu aplicativo de IA suportar tarefas agendadas, ele pode verificar sua agenda periodicamente.

Documentação técnica

• Catálogo de capacidades MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas e entradas
• Documentação de desenvolvimento
• Documentação de publicação
• Referência da API do Google Agenda

Suporte

Encontrou um bug ou precisa de um cenário? Crie um problema ou escreva no Telegram.

Você chegou ao final!