Servidor MCP Google Calendar | Awesome MCP Servers

Servidor MCP do Google Calendar

Este servidor MCP permite que o Claude interaja com seu Google Calendar, habilitando recursos como listar eventos, criar reuniões e encontrar horários livres.

Pré-requisitos

Node.js (v16 ou superior)
Aplicativo Claude Desktop
Um projeto do Google Cloud
API do Google Calendar habilitada
Credenciais OAuth 2.0

Instruções de Configuração

1. Criar um projeto do Google Cloud

Vá para o Google Cloud Console
Crie um novo projeto ou selecione um existente
Habilite a API do Google Calendar:
- Vá para "APIs & Services" > "Library"
- Pesquise por "Google Calendar API"
- Clique em "Enable"

2. Configurar a Tela de Consentimento OAuth

Vá para "APIs & Services" > "OAuth consent screen"
Selecione o tipo de usuário "External" (a menos que você tenha uma organização do Google Workspace)
Preencha as informações necessárias:
- Nome do aplicativo
- E-mail de suporte ao usuário
- Informações de contato do desenvolvedor
Adicione os seguintes escopos:
- https://www.googleapis.com/auth/calendar
- https://www.googleapis.com/auth/calendar.events
Adicione seu endereço de e-mail como usuário de teste

3. Criar Credenciais OAuth 2.0

Vá para "APIs & Services" > "Credentials"
Clique em "Create Credentials" > "OAuth client ID"
Selecione "Desktop app" como o tipo de aplicativo
Dê um nome ao seu cliente (por exemplo, "MCP Calendar Client")
Clique em "Create"
Baixe o arquivo de configuração do cliente (você precisará do client ID e do client secret)

4. Obter o Refresh Token

Crie um novo arquivo chamado getToken.js:

const { google } = require('googleapis');
const http = require('http');
const url = require('url');

// Replace these with your OAuth 2.0 credentials
const CLIENT_ID = 'your-client-id';
const CLIENT_SECRET = 'your-client-secret';
const REDIRECT_URI = 'http://localhost:3000/oauth2callback';

// Configure OAuth2 client
const oauth2Client = new google.auth.OAuth2(
  CLIENT_ID,
  CLIENT_SECRET,
  REDIRECT_URI
);

// Define scopes
const scopes = [
  'https://www.googleapis.com/auth/calendar',
  'https://www.googleapis.com/auth/calendar.events'
];

async function getRefreshToken() {
  return new Promise((resolve, reject) => {
    try {
      // Create server to handle OAuth callback
      const server = http.createServer(async (req, res) => {
        try {
          const queryParams = url.parse(req.url, true).query;
          
          if (queryParams.code) {
            // Get tokens from code
            const { tokens } = await oauth2Client.getToken(queryParams.code);
            console.log('\n=================');
            console.log('Refresh Token:', tokens.refresh_token);
            console.log('=================\n');
            console.log('Save this refresh token in your configuration!');
            
            // Send success response
            res.end('Authentication successful! You can close this window.');
            
            // Close server
            server.close();
            resolve(tokens);
          }
        } catch (error) {
          console.error('Error getting tokens:', error);
          res.end('Authentication failed! Please check console for errors.');
          reject(error);
        }
      }).listen(3000, () => {
        // Generate auth url
        const authUrl = oauth2Client.generateAuthUrl({
          access_type: 'offline',
          scope: scopes,
          prompt: 'consent'  // Force consent screen to ensure refresh token
        });

        console.log('1. Copy this URL and paste it in your browser:');
        console.log('\n', authUrl, '\n');
        console.log('2. Follow the Google authentication process');
        console.log('3. Wait for the refresh token to appear here');
      });

    } catch (error) {
      console.error('Server creation error:', error);
      reject(error);
    }
  });
}

// Run the token retrieval
getRefreshToken().catch(console.error);

Instale a dependência necessária:

npm install googleapis

Atualize o script com suas credenciais OAuth:
- Substitua your-client-id pelo seu client ID real
- Substitua your-client-secret pelo seu client secret real
Execute o script:

node getToken.js

Siga as instruções no console:
- Copie a URL fornecida
- Cole-a no seu navegador
- Complete o processo de autenticação do Google
- Copie o refresh token que aparece no console

5. Configurar o Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

Para MacOS:

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

Para Windows:

code %AppData%\Claude\claude_desktop_config.json

Adicione ou atualize a configuração:

{
    "mcpServers": {
        "google-calendar": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/YOUR/build/index.js"
            ],
            "env": {
                "GOOGLE_CLIENT_ID": "your_client_id_here",
                "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
                "GOOGLE_REDIRECT_URI": "http://localhost",
                "GOOGLE_REFRESH_TOKEN": "your_refresh_token_here"
            }
        }
    }
}

Salve o arquivo e reinicie o Claude Desktop

Configuração Inicial do Projeto

Crie um novo diretório para o seu projeto:

mkdir google-calendar-mcp
cd google-calendar-mcp

Inicialize um novo projeto npm:

npm init -y

Instale as dependências:

npm install @modelcontextprotocol/sdk googleapis google-auth-library zod
npm install -D @types/node typescript

Crie um arquivo tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Atualize o package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\""
  }
}

Crie seu diretório de origem:

mkdir src

Crie um arquivo .env para desenvolvimento local (não envie este arquivo para o controle de versão):

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost
GOOGLE_REFRESH_TOKEN=your_refresh_token_here

Compilação e Execução

Compile o servidor:

npm run build

O servidor iniciará automaticamente quando você abrir o Claude Desktop

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas:

list_events: Listar eventos do calendário em um intervalo de tempo especificado
create_event: Criar um novo evento no calendário
update_event: Atualizar um evento existente no calendário
delete_event: Excluir um evento do calendário
find_free_time: Encontrar horários disponíveis no calendário

Exemplo de Uso no Claude

Após a configuração, você pode usar comandos como:

"Mostre-me meus eventos do calendário para a próxima semana"
"Agende uma reunião com [email_id] amanhã às 14h por 1 hora"
"Encontre um horário livre de 30 minutos esta tarde"
"Atualize minha reunião das 15h para as 16h"
"Cancele minha reunião com o ID [event_id]"

Solução de Problemas

Problemas Comuns

Ferramentas não aparecem no Claude:
- Verifique os logs do Claude Desktop: tail -f ~/Library/Logs/Claude/mcp*.log
- Confirme se todas as variáveis de ambiente estão definidas corretamente
- Garanta que o caminho para index.js seja absoluto e correto
Erros de Autenticação:
- Verifique se suas credenciais OAuth estão corretas
- Verifique se o refresh token é válido
- Garanta que os escopos necessários estejam habilitados
Problemas de Conexão com o Servidor:
- Verifique se o servidor foi compilado com sucesso
- Verifique as permissões do arquivo em build/index.js (deve ser 755)
- Tente executar o servidor diretamente: node /path/to/build/index.js

Visualizando Logs

Para visualizar os logs do servidor:

# For MacOS/Linux:
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# For Windows:
Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20

Variáveis de Ambiente

Se você estiver recebendo erros de variáveis de ambiente, verifique cada uma:

GOOGLE_CLIENT_ID: Deve começar com algo como "123456789-..."
GOOGLE_CLIENT_SECRET: Geralmente termina em ".apps.googleusercontent.com"
GOOGLE_REDIRECT_URI: Deve ser "http://localhost"
GOOGLE_REFRESH_TOKEN: Uma string longa que não expira

Considerações de Segurança

Mantenha suas credenciais OAuth seguras
Não envie credenciais para o controle de versão
Use variáveis de ambiente para dados sensíveis
Rotacione os refresh tokens regularmente
Monitore o uso da API no Google Cloud Console

Licença

Licença MIT - Consulte o arquivo LICENSE para obter detalhes.

Suporte

Se você encontrar algum problema:

Verifique a seção de solução de problemas acima
Revise os logs do Claude Desktop
Abra uma issue no GitHub
Entre em contato com o mantenedor

Google Calendar

Documentação