Google Calendar

Um servidor MCP para o Google Calendar, permitindo que LLMs leiam, criem e gerenciem eventos de calendário.

GitHub
1

Documentação

Google Calendar MCP Server

Este é um servidor Model Context Protocol (MCP) que fornece integração com o Google Calendar. Ele permite que LLMs leiam, criem e gerenciem eventos de calendário por meio de uma interface padronizada.

Recursos

  • Listar calendários disponíveis
  • Listar eventos de um calendário
  • Criar novos eventos de calendário
  • Atualizar eventos existentes
  • Excluir eventos
  • Processar eventos a partir de capturas de tela e imagens

Requisitos

  1. Node.js 16 ou superior
  2. TypeScript 5.3 ou superior
  3. Um projeto do Google Cloud com a API Calendar habilitada
  4. Credenciais OAuth 2.0 (Client ID e Client Secret)

Estrutura do Projeto

google-calendar-mcp/
├── src/           # TypeScript source files
├── build/         # Compiled JavaScript output
├── llm/           # LLM-specific configurations and prompts
├── package.json   # Project dependencies and scripts
└── tsconfig.json  # TypeScript configuration

Configuração do Google Cloud

  1. Acesse o Google Cloud Console
  2. Crie um novo projeto ou selecione um existente.
  3. Habilite a Google Calendar API para o seu projeto. Certifique-se de que o projeto correto esteja selecionado na barra superior antes de habilitar a API.
  4. Crie credenciais OAuth 2.0:
    • Vá para Credenciais
    • Clique em "Criar credenciais" > "ID do cliente OAuth"
    • Escolha "Dados do usuário" para o tipo de dados que o aplicativo acessará
    • Adicione o nome do seu aplicativo e informações de contato
    • Adicione os seguintes escopos (opcional):
      • https://www.googleapis.com/auth/calendar.events
    • Selecione "Aplicativo para desktop" como o tipo de aplicativo
    • Adicione seu endereço de e-mail como usuário de teste na tela de consentimento OAuth
      • Observação: levará alguns minutos para que o usuário de teste seja adicionado. O consentimento OAuth não permitirá que você prossiga até que o usuário de teste seja propagado.

Instalação

  1. Clone o repositório
  2. Instale as dependências: 
    npm install
  3. Compile o código TypeScript: 
    npm run build
  4. Baixe suas credenciais OAuth do Google no Google Cloud Console (em "Credenciais") e renomeie o arquivo para gcp-oauth.keys.json e coloque-o no diretório raiz do projeto.

Scripts Disponíveis

  • npm run build - Compila o código TypeScript
  • npm run build:watch - Compila o TypeScript em modo de observação para desenvolvimento
  • npm run dev - Inicia o servidor em modo de desenvolvimento usando ts-node
  • npm run auth - Inicia o servidor de autenticação para o fluxo OAuth do Google

Autenticação

O servidor suporta fluxos de autenticação automáticos e manuais:

Autenticação Automática (Recomendada)

  1. Coloque suas credenciais OAuth do Google em um arquivo chamado gcp-oauth.keys.json no diretório raiz do projeto.
  2. Inicie o servidor MCP: 
    npm start
  3. Se nenhum token de autenticação válido for encontrado, o servidor automaticamente:
    • Iniciará um servidor de autenticação (nas portas 3000-3004)
    • Abrirá uma janela do navegador para o fluxo OAuth
    • Salvará os tokens com segurança após a autenticação
    • Encerrará o servidor de autenticação
    • Continuará a operação normal do servidor MCP

O servidor gerencia automaticamente a renovação de tokens e a reautenticação quando necessário:

  • Os tokens são renovados automaticamente antes da expiração
  • Se a renovação falhar, mensagens de erro claras orientam você pela reautenticação
  • Os arquivos de token são armazenados com segurança com permissões restritas

Autenticação Manual

Para usuários avançados ou solução de problemas, você pode executar manualmente o fluxo de autenticação:

npm run auth

Isso irá:

  1. Iniciar o servidor de autenticação
  2. Abrir uma janela do navegador para o fluxo OAuth
  3. Salvar os tokens e sair

Notas de Segurança

  • As credenciais OAuth são armazenadas em gcp-oauth.keys.json
  • Os tokens de autenticação são armazenados em .gcp-saved-tokens.json com permissões 600
  • Os tokens são renovados automaticamente em segundo plano
  • A integridade do token é validada antes de cada chamada de API
  • O servidor de autenticação é encerrado automaticamente após a autenticação bem-sucedida
  • Nunca envie credenciais OAuth ou arquivos de token para o controle de versão

Uso

O servidor expõe as seguintes ferramentas:

  • list-calendars: Lista todos os calendários disponíveis
  • list-events: Lista eventos de um calendário
  • create-event: Cria um novo evento de calendário
  • update-event: Atualiza um evento de calendário existente
  • delete-event: Exclui um evento de calendário

Usando com o Claude Desktop

  1. Adicione esta configuração ao seu arquivo de configuração do Claude Desktop. Ex.: /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json:

    {
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["path/to/build/index.js"]
    }
  }
}

  2. Reinicie o Claude Desktop

Exemplo de Uso

Além das capacidades normais que você esperaria de uma integração de calendário, você também pode fazer coisas realmente dinâmicas, como adicionar eventos a partir de capturas de tela e imagens, e muito mais.

  1. Adicione eventos a partir de capturas de tela e imagens:

    Add this event to my calendar based on the attached screenshot.

    Formatos de imagem suportados: PNG, JPEG, GIF As imagens podem conter detalhes do evento, como data, hora, local e descrição

  2. Verifique a presença:

    Which events tomorrow have attendees who have not accepted the invitation?

  3. Coordene eventos automaticamente:

    Here's some available that was provided to me by someone I am interviewing. Take a look at the available times and create an event for me to interview them that is free on my work calendar.

  4. Forneça sua própria disponibilidade:

    Please provide availability looking at both my personal and work calendar for this upcoming week. Choose times that work well for normal working hours on the East Coast. Meeting time is 1 hour

Desenvolvimento

Solução de Problemas

Problemas comuns e soluções:

  1. O token OAuth expira após uma semana (7 dias)

    • Aplicativos em modo de teste, em vez de produção, precisarão passar pelo fluxo OAuth novamente após uma semana.

  2. Erros de Token OAuth

    • Certifique-se de que seu gcp-oauth.keys.json esteja formatado corretamente
    • Tente excluir .gcp-saved-tokens.json e reautenticar

  3. Erros de Compilação TypeScript

    • Certifique-se de que todas as dependências estejam instaladas: npm install
    • Verifique se a versão do seu Node.js atende aos pré-requisitos
    • Limpe o diretório de compilação: rm -rf build/

  4. Problemas de Processamento de Imagens

    • Verifique se o formato da imagem é suportado
    • Certifique-se de que a imagem contenha texto claro e legível

Notas de Segurança

  • O servidor é executado localmente e requer autenticação OAuth
  • As credenciais OAuth devem ser armazenadas em gcp-oauth.keys.json na raiz do projeto
  • Os tokens de autenticação são armazenados em .gcp-saved-tokens.json com permissões de arquivo restritas
  • Os tokens são renovados automaticamente quando expiram
  • Nunca envie suas credenciais OAuth ou arquivos de token para o controle de versão
  • Para uso em produção, obtenha a verificação do seu aplicativo OAuth pelo Google

Licença

MIT