Google Calendar

Integre o Google Calendar com segurança aprimorada usando credenciais OAuth2.

GitHub
59

Documentação

Servidor MCP do Google Calendar

Apr-15-2025 12-17-08

🔔 AVISO DE ATUALIZAÇÃO DE VERSÃO 🔔
A versão 2.0.0 migra para a revisão de protocolo MCP 2026-07-28 e implementa PKCE no fluxo OAuth. Ela requer Node.js 20 ou mais recente. Consulte o histórico de versões abaixo para a lista completa de alterações.

Version License

日本語 English

Visão Geral do Projeto

O Servidor MCP do Google Calendar é uma implementação de servidor MCP (Model Context Protocol) que permite a integração entre o Google Calendar e o Claude Desktop. Este projeto permite que o Claude interaja com o Google Calendar do usuário, fornecendo a capacidade de exibir, criar, atualizar e excluir eventos de calendário por meio de interação em linguagem natural.

Recursos Principais

  • Integração com Google Calendar: Fornece uma ponte entre o Claude Desktop e a API do Google Calendar
  • Implementação MCP: Segue a especificação do Model Context Protocol para integração de ferramentas de assistentes de IA
  • Autenticação OAuth2: Gerencia o fluxo de autenticação da API do Google com segurança
  • Gerenciamento de eventos: Suporta operações abrangentes de eventos de calendário (obter, criar, atualizar, excluir)
  • Suporte a cores: Capacidade de definir e atualizar cores de eventos usando o parâmetro colorId
  • Transporte STDIO: Usa entrada/saída padrão para comunicação com o Claude Desktop

Arquitetura Técnica

Este projeto utiliza:

  • TypeScript: Para desenvolvimento de código com segurança de tipos
  • SDK MCP: Usa @modelcontextprotocol/server v2 (revisão de protocolo 2026-07-28, com as revisões de 2025 ainda servidas para clientes mais antigos)
  • API do Google: Usa googleapis para acesso à API do Google Calendar
  • Hono: Framework web leve e rápido para o servidor de autenticação
  • google-auth-library: Conduz o fluxo de código de autorização OAuth2 com PKCE (S256)
  • Zod: Implementa validação de esquema para dados de requisição/resposta
  • Configuração baseada em ambiente: Usa dotenv para gerenciamento de configuração
  • AES-256-GCM: Para criptografia de tokens usando o módulo crypto do Node.js
  • Open: Para abertura automática do navegador durante a autenticação
  • Readline: Para entrada manual de autenticação em ambientes de servidor
  • Jest: Para testes unitários e cobertura
  • GitHub Actions: Para CI/CD

Componentes Principais

  1. Servidor MCP: Implementação central do servidor que gerencia a comunicação com o Claude Desktop
  2. Ferramentas do Google Calendar: Operações de calendário (recuperação, criação, atualização, exclusão)
  3. Manipulador de Autenticação: Gerenciamento do fluxo OAuth2 com a API do Google
  4. Validação de Esquema: Garantia da integridade dos dados em todas as operações
  5. Gerenciador de Tokens: Tratamento seguro dos tokens de autenticação

Ferramentas Disponíveis

Este servidor MCP fornece as seguintes ferramentas para interagir com o Google Calendar:

1. getEvents

Recupera eventos de calendário com várias opções de filtro.

Parâmetros:

  • calendarId (opcional): ID do calendário (usa o calendário principal se omitido, string vazia, nulo ou indefinido)
  • timeMin (opcional): Horário de início para recuperação de eventos (formato ISO 8601, ex.: "2025-03-01T00:00:00Z"). Strings vazias, nulos ou valores indefinidos são ignorados
  • timeMax (opcional): Horário de término para recuperação de eventos (formato ISO 8601). Strings vazias, nulos ou valores indefinidos são ignorados
  • maxResults (opcional): Número máximo de eventos a recuperar (padrão: 10)
  • orderBy (opcional): Ordem de classificação ("startTime" ou "updated"). O padrão é "startTime" se string vazia, nulo ou indefinido

2. createEvent

Cria um novo evento de calendário.

Parâmetros:

  • calendarId (opcional): ID do calendário (usa o calendário principal se omitido)
  • event: Objeto de detalhes do evento contendo:
    • summary (obrigatório): Título do evento
    • description (opcional): Descrição do evento
    • location (opcional): Local do evento
    • start: Objeto de horário de início com:
      • dateTime (opcional): Formato ISO 8601 (ex.: "2025-03-15T09:00:00+09:00")
      • date (opcional): Formato AAAA-MM-DD para eventos de dia inteiro
      • timeZone (opcional): Fuso horário (ex.: "Asia/Tokyo")
    • end: Objeto de horário de término (mesmo formato do início)
    • attendees (opcional): Matriz de participantes com e-mail e displayName opcional
    • colorId (opcional): ID da cor do evento (1-11)
    • recurrence (opcional): Matriz de regras de recorrência no formato RFC5545 (ex.: ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"])

3. updateEvent

Atualiza um evento de calendário existente. A função primeiro busca os dados do evento existente e os mescla com os dados de atualização, preservando os campos que não estão incluídos na solicitação de atualização.

Parâmetros:

  • calendarId (opcional): ID do calendário (usa o calendário principal se omitido)
  • eventId (obrigatório): ID do evento a ser atualizado
  • event: Objeto de detalhes do evento contendo campos a atualizar (mesma estrutura do createEvent, todos os campos opcionais)
    • Somente os campos fornecidos explicitamente serão atualizados
    • Os campos não incluídos na solicitação de atualização manterão seus valores existentes
    • Isso permite atualizações parciais sem perda de dados
    • O parâmetro recurrence pode ser atualizado para modificar padrões de eventos recorrentes

4. deleteEvent

Exclui um evento de calendário.

Parâmetros:

  • calendarId (opcional): ID do calendário (usa o calendário principal se omitido)
  • eventId (obrigatório): ID do evento a ser excluído

5. authenticate

Reautentica com o Google Calendar. Isso é útil quando você deseja alternar entre diferentes contas do Google sem precisar reiniciar o Claude.

Parâmetros:

  • Nenhum

Diretrizes de Desenvolvimento

Ao adicionar novas funções, modificar código ou corrigir bugs, aumente semanticamente a versão para cada alteração usando o comando npm version. Além disso, certifique-se de que seu código seja claro e siga todas as regras de codificação necessárias, como OOP. O script de versão executará automaticamente o npm install quando a versão for atualizada, mas você ainda deve compilar, executar o lint e testar seu código antes de enviá-lo.

Estrutura do Código

  • src/: Diretório do código-fonte
    • auth/: Tratamento de autenticação (fluxo OAuth com PKCE, armazenamento de tokens)
    • calendar/: Integração com a API do Google Calendar
    • config/: Configurações e validação
    • mcp/: Implementação do servidor MCP
      • tools/: Manipuladores de ferramentas do Google Calendar
    • utils/: Funções utilitárias e auxiliares

Boas Práticas

  • Tipagem adequada de acordo com as boas práticas do TypeScript
  • Manutenção de tratamento abrangente de erros
  • Garantia do fluxo de autenticação adequado
  • Manutenção das dependências atualizadas
  • Documentação clara para todas as funções
  • Implementação de boas práticas de segurança
  • Conformidade com os padrões de autenticação OAuth 2.1
  • Uso de validação de esquema para todos os dados de entrada/saída

Testes

  • Implementação de testes unitários para funcionalidades principais
  • Teste completo do fluxo de autenticação
  • Verificação da manipulação do calendário contra a API do Google
  • Execução de testes com relatórios de cobertura
  • Garantia de inclusão de testes de segurança

Implantação

Este pacote é publicado no npm como @takumi0706/google-calendar-mcp:

npx @takumi0706/google-calendar-mcp@2.0.0

Pré-requisitos

  1. Node.js 20 ou mais recente
  2. Crie um projeto no Google Cloud e ative a API do Google Calendar
  3. Configure as credenciais OAuth2 no Console do Google Cloud
  4. Configure as variáveis de ambiente:
# Create a .env file with your Google OAuth credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# Optional: Token encryption key (auto-generated if not provided)
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# Optional: Auth server port and host (default port: 4153, host: localhost)
AUTH_PORT=4153
AUTH_HOST=localhost
# Optional: MCP server port and host (default port: 3000, host: localhost)
PORT=3000
HOST=localhost
# Optional: Enable manual authentication (useful when localhost is not accessible)
USE_MANUAL_AUTH=true

Configuração do Claude Desktop

Adicione o servidor ao seu claude_desktop_config.json. Se você estiver executando em um ambiente onde o localhost não é acessível, adicione a variável de ambiente USE_MANUAL_AUTH definida como "true".

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": [
        "-y",
        "@takumi0706/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
      }
    }
  }
}

Considerações de Segurança

  • Tokens OAuth são armazenados apenas em memória (não armazenados em armazenamento baseado em arquivo). Eles são perdidos na reinicialização, o que significa que a reautenticação é necessária após cada reinicialização.
  • Credenciais sensíveis devem ser fornecidas como variáveis de ambiente
  • Criptografia de tokens usando AES-256-GCM enquanto os tokens estão em memória. Observe que a chave reside no mesmo processo que o texto cifrado, portanto, isso protege contra inspeção casual da memória do processo, não contra um invasor que já pode ler a memória deste processo.
  • PKCE (S256) no fluxo de código de autorização, com um code_verifier gerado por solicitação e nunca enviado ao endpoint de autorização
  • Validação do parâmetro de estado para proteção CSRF: estado CSPRNG de 256 bits, comparado em tempo constante, de uso único e com expiração após 10 minutos
  • URI de redirecionamento fixa obtida da configuração em vez do cabeçalho Host da solicitação
  • Validação de entrada com esquema Zod
  • Escape de HTML em cada valor interpolado nas páginas de resultado do OAuth

Para mais detalhes, consulte SECURITY.md.

Manutenção

  • Atualizações regulares para manter a compatibilidade com a API do Google Calendar
  • Atualizações de versão são documentadas no README.md

Solução de Problemas

Se você encontrar algum problema:

  1. Certifique-se de que suas credenciais OAuth do Google estejam configuradas corretamente
  2. Garanta que você tenha permissões suficientes para acesso à API do Google Calendar
  3. Verifique se a configuração do seu Claude Desktop está correta

Erros Comuns

  • Erros de Análise JSON: Se você vir erros como Unexpected non-whitespace character after JSON at position 4 (line 1 column 5), geralmente é devido a mensagens JSON-RPC malformadas. Este problema foi corrigido na versão 0.6.7 e posteriores. Se você ainda estiver enfrentando esses erros, atualize para a versão mais recente.
  • Erros de Autenticação: Verifique suas credenciais OAuth do Google
  • Parâmetro de estado inválido: Se você vir Authentication failed: Invalid state parameter ao reautenticar, atualize para a versão 1.0.3 ou posterior, que corrige o gerenciamento do ciclo de vida do servidor OAuth. Em versões mais antigas, talvez seja necessário fechar a porta 4153 e reiniciar o aplicativo.
  • Erros de Conexão: Certifique-se de que apenas uma instância do servidor esteja em execução
  • Problemas de Desconexão: Garanta que seu servidor esteja tratando mensagens MCP corretamente sem sockets TCP personalizados
  • Não é possível acessar o localhost: Se você estiver executando o aplicativo em um ambiente onde o localhost não é acessível (como um servidor remoto ou contêiner), ative a autenticação manual definindo USE_MANUAL_AUTH=true. Isso permitirá que você insira manualmente o código de autorização mostrado pelo Google após autorizar o aplicativo.
  • Erros de Validação de Parâmetros MCP: Se você vir o erro -32602 com parâmetros de string vazia, atualize para a versão 1.0.7 ou posterior, que trata strings vazias, nulos e valores indefinidos corretamente.

Histórico de Versões

Alterações da Versão 2.0.0

Segurança

  • Implementado PKCE (S256) no fluxo de código de autorização OAuth. Versões anteriores documentavam PKCE, mas nunca enviavam um code_challenge.
  • O parâmetro state agora é um valor CSPRNG de 256 bits, comparado em tempo constante, de uso único e com expiração após 10 minutos. Anteriormente, era gerado com Math.random().
  • Corrigido um XSS refletido na página de erro do OAuth: os detalhes do erro agora são registrados em vez de interpolados no HTML, e cada valor interpolado é escapado.
  • redirect_uri é fixado ao valor configurado em vez de ser derivado do cabeçalho Host da solicitação.
  • O servidor de autorização local agora aborta quando sua porta já está em uso, em vez de assumir que outra instância está servindo o fluxo.
  • TOKEN_ENCRYPTION_KEY agora deve ter exatamente 64 caracteres hexadecimais; chaves inválidas e todas em zero são rejeitadas na inicialização.
  • Resolvidas todas as vulnerabilidades conhecidas nas dependências de produção.

Protocolo

  • Migrado para @modelcontextprotocol/server v2 e revisão de protocolo 2026-07-28. As revisões de 2025 ainda são servidas, portanto, os clientes existentes continuam funcionando.
  • tools/list agora anuncia o esquema real, portanto, objetos aninhados, como o argumento event de createEvent, expõem suas propriedades. Anteriormente, eles eram opacos.
  • prompts/get agora está implementado. O servidor anunciava dez prompts que não podiam ser buscados.
  • resources/read agora retorna a forma que a especificação exige.
  • initialize não vaza mais internals do Zod por meio de capabilities.

Alteração de Quebra

  • Requer Node.js 20 ou mais recente.

Outros

  • Migrou o toolchain para pnpm, atualizou googleapis, hono e zod, e removeu @hono/oauth-providers.
  • Removeu any e asserções de tipo do código enviado, aplicado por lint.

Alterações da Versão 1.0.7

  • Validação aprimorada de parâmetros para ferramentas MCP para lidar corretamente com strings vazias, null e valores indefinidos
  • Corrigido erro MCP -32602 quando parâmetros de string vazia eram passados para a ferramenta getEvents
  • Melhorada a função preprocessArgs para ignorar valores vazios, permitindo que os padrões do esquema Zod sejam aplicados corretamente
  • Adicionada cobertura abrangente de testes para o tratamento de parâmetros vazios

Alterações da Versão 1.0.6

  • Corrigido o escopo que não é necessário neste servidor MCP do Google Calendar

Alterações da Versão 1.0.5

  • Adicionado suporte para eventos recorrentes através do parâmetro recurrence nas ferramentas createEvent e updateEvent
  • Permite a criação e modificação de eventos recorrentes diretamente, sem configuração manual

Alterações da Versão 1.0.4

  • Versão de manutenção com atualização do número da versão
  • Sem alterações funcionais em relação à versão 1.0.3
  • Garante compatibilidade com as dependências mais recentes

Alterações da Versão 1.0.3

  • Adicionada nova ferramenta authenticate para permitir reautenticação sem reiniciar o Claude
  • Tornou possível alternar entre diferentes contas do Google durante uma sessão
  • Exposta a funcionalidade de autenticação através da interface MCP
  • Experiência do usuário aprimorada ao eliminar a necessidade de reiniciar para alternar de conta
  • Adicionada opção de autenticação manual para ambientes onde localhost não é acessível
  • Implementada interface readline para inserir códigos de autorização manualmente
  • Adicionada variável de ambiente USE_MANUAL_AUTH para habilitar autenticação manual
  • Atualizada a dependência zod para a versão mais recente (3.24.2)
  • Validação de esquema melhorada com os recursos mais recentes do zod
  • Estabilidade e segurança do código aprimoradas
  • Corrigido erro "Invalid state parameter" durante a reautenticação
  • Modificado o servidor OAuth para iniciar sob demanda e desligar após a autenticação
  • Gerenciamento do ciclo de vida do servidor melhorado para prevenir conflitos de porta
  • Tratamento de erros aprimorado para o fluxo de autenticação

Alterações da Versão 1.0.2

  • Corrigida a função updateEvent para preservar dados existentes de eventos ao realizar atualizações parciais
  • Adicionada a função getEvent para buscar dados existentes de eventos antes de atualizar
  • Modificado updateEvent para mesclar dados de atualização com dados existentes para evitar perda de dados
  • Validação de esquema atualizada para tornar todos os campos opcionais em solicitações de atualização
  • Documentação melhorada para a função updateEvent

Alterações da Versão 1.0.1

  • Corrigido problema de compatibilidade com Node.js v20.9.0+ e o pacote 'open' (v10+)
  • Substituída importação estática por importação dinâmica para o pacote 'open' exclusivo para ESM
  • Tratamento de erros melhorado para abertura do navegador durante autenticação OAuth
  • Comentários de código aprimorados para melhor manutenibilidade

Alterações da Versão 1.0.0

  • Lançamento da versão principal marcando prontidão para produção
  • Refatoração abrangente do código para melhor manutenibilidade
  • Internacionalização de todas as mensagens e comentários (traduzido do japonês para o inglês)
  • Consistência e legibilidade do código aprimoradas
  • Mensagens de erro melhoradas para melhor experiência do usuário
  • Documentação atualizada para refletir o estado atual do projeto
  • Padronização do estilo de codificação em todo o código

Alterações da Versão 0.8.0

  • Fluxo de autenticação OAuth aprimorado para lidar com problemas de refresh token
  • Adicionado parâmetro prompt: 'consent' para forçar o Google a mostrar a tela de consentimento e fornecer um novo refresh token
  • Fluxo de autenticação modificado para funcionar apenas com access token se um refresh token não estiver disponível
  • Lógica de renovação de token melhorada para lidar com casos onde não há refresh token ou se o refresh token é inválido
  • Armazenamento de token atualizado para salvar access tokens renovados para melhor gerenciamento de tokens
  • Corrigido possível loop infinito na lógica de renovação de token

Instalação

Início Rápido (Recomendado)

Instale diretamente do npm:

npm install -g @takumi0706/google-calendar-mcp

Instalação Manual

Para desenvolvimento ou personalização:

# Clone the repository
git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

Implantação em Produção

Para uso em produção, o servidor requer credenciais OAuth válidas do Google. O servidor falhará ao iniciar sem credenciais adequadas, garantindo conformidade de segurança.

Testes

Para executar os testes:

# Run all tests
npm test

# Run tests with coverage report
npm test -- --coverage

Licença

MIT