Google Calendar

Interaja com as APIs do Google Calendar para gerenciar eventos e calendários.

GitHub
2

Documentação

🗓️ Servidor MCP do Google Calendar

Este projeto integra as APIs do Google Calendar v3 com um Servidor MCP (Model Context Protocol) personalizado, permitindo interação em linguagem natural com seu calendário por meio de ferramentas como o Claude Desktop.

Ele atua como uma ponte entre seus dados de calendário e um LLM usando streaming HTTP compatível com MCP.

🧠 Visão Geral

Este projeto contém dois servidores principais:

1. 🔐 Servidor OAuth do Google

  • Gerencia o fluxo OAuth 2.0
  • Armazena e atualiza tokens de acesso em um arquivo de sessão local

2. 🤖 Servidor MCP

🚀 Começando

Passo 1: 🔧 Configurar as Credenciais da API do Google

  1. Acesse o Google Cloud Console
  2. Crie ou selecione um projeto
  3. Ative a API do Google Calendar
  4. Vá para Credenciais → Criar ID de cliente OAuth 2.0
    • Escolha Aplicativo de desktop
    • Configure a marcação e adicione e-mails de usuários de teste no público-alvo
  5. Baixe as credenciais OAuth como client_secret.json
  6. Coloque este arquivo na raiz do projeto

Passo 2: 📦 Instalar Dependências

poetry install

Step 3: 🚪 Start the OAuth Server

poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000
  • Isso deve abrir automaticamente um navegador para autenticação OAuth.
  • Se não abrir, visite http://0.0.0.0:8000/google_oauth/
  • Após a autenticação bem-sucedida, você verá uma página de sucesso.
  • Um arquivo session.json será criado com seus tokens de acesso/atualização.

OAuth Success Page

Passo 4: 🧩 Executar o Servidor MCP

poetry run python src/server.py

Isso inicia um servidor HTTP compatível com MCP e transmitível em http://localhost:8080/mcp

Passo 5: 🧠 Conectar o Cliente MCP (Claude Desktop)

Atualize o arquivo de configuração em:

~/Library/Application Support/Claude/claude_desktop_config.json

Adicione a seguinte entrada:

{
  "mcpServers": {
    "google-calendar-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp"
      ]
    }
  }
}

Passo 6: ✅ Verificar a Integração

  • Abra as configurações do Claude Desktop.
  • Se o servidor MCP foi adicionado corretamente, ele aparecerá em Configurações -> integrações

MCP client integrations

🧠 Demonstração

https://github.com/user-attachments/assets/27a8e5ee-8f2f-40c7-bdfc-1caa93767efb

🧱 Estrutura do Projeto

project-root/
├── client_secret.json         # Google OAuth credentials
├── session.json               # Access/refresh token storage
├── pyproject.toml             # Poetry project config
├── README.md                  

└── src/
    ├── main.py                # FastAPI app for OAuth server
    ├── server.py              # MCP-compatible server
    ├── settings.py            # App settings and constants

    ├── api/
    │   └── oauth_callback.py  # OAuth endpoint logic

    ├── core/
    │   ├── calendar_client.py # Google Calendar API wrapper
    │   ├── mcp_tools.py       # Tools exposed to MCP clients
    │   ├── oauth_manager.py   # OAuth initiation and flow
    │   └── session_manager.py # Token handling

    └── gcalendar_types/       # Typed definitions for Calendar v3 API

🧩 Dependências