Google Calendar MCP Server

Uma implementação do Model Context Protocol (MCP) para o Google Calendar que permite a interação com eventos do calendário através de CLI ou Server-Sent Events (SSE).

Funcionalidades

- Listar eventos do calendário
- Criar novos eventos
- Atualizar eventos existentes
- Excluir eventos
- Encontrar horários disponíveis

Pré-requisitos

- Node.js 18 ou superior
- Conta Google com acesso à API do Google Calendar
- Credenciais OAuth 2.0 do Google Cloud Console

Configuração

1. Copie o arquivo .env.example para .env:

   cp .env.example .env

   

2. Configure suas credenciais OAuth 2.0 do Google no arquivo .env:

   GOOGLE_CLIENT_ID=seu-client-id

   GOOGLE_CLIENT_SECRET=seu-client-secret

   GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback

   GOOGLE_REFRESH_TOKEN=seu-refresh-token

   PORT=3334

   

3. Instale as dependências:

   npm install

   

4. Compile o código:

   npm run build

   

Uso

Execução como servidor HTTP/SSE

Inicie o servidor HTTP/SSE:

npm run start:http

Isso iniciará o servidor na porta especificada (padrão: 3334).

Endpoints disponíveis:
- GET /sse - Conectar ao stream SSE
- POST /messages - Enviar mensagens para o servidor

Execução como CLI (stdio)

Execute o servidor em modo stdio para uso como ferramenta CLI:

npm run start:stdio

Integração com MCP Clients

Claude Desktop

Para usar este servidor com o Claude Desktop, adicione a seguinte configuração ao arquivo de configuração do Claude:

No MacOS:

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

No Windows:

code %AppData%\Claude\claude_desktop_config.json

Adicione a configuração:

{

  "mcpServers": {

    "google-calendar": {

      "command": "node",

      "args": [

        "/caminho/absoluto/para/o/build/index.js"

      ],

      "env": {

        "GOOGLE_CLIENT_ID": "seu-client-id",

        "GOOGLE_CLIENT_SECRET": "seu-client-secret",

        "GOOGLE_REDIRECT_URI": "seu-redirect-uri",

        "GOOGLE_REFRESH_TOKEN": "seu-refresh-token"

      }

    }

  }

}

Integração com outros Clientes MCP

Para outros clientes MCP que suportam comunicação via SSE, aponte-os para os endpoints:
- SSE Endpoint: http://localhost:3334/sse
- Message Endpoint: http://localhost:3334/messages

Ferramentas disponíveis

O servidor Google Calendar MCP fornece as seguintes ferramentas:

list_events

Lista eventos em um intervalo de tempo especificado.

{
  "timeMin": "2023-09-01T00:00:00Z",
  "timeMax": "2023-09-30T23:59:59Z",
  "maxResults": 10
}

create_event

Cria um novo evento no calendário.

{
  "summary": "Reunião importante",
  "description": "Discussão sobre o projeto XYZ",
  "startTime": "2023-09-15T14:00:00Z",
  "endTime": "2023-09-15T15:00:00Z",
  "attendees": ["pessoa1@exemplo.com", "pessoa2@exemplo.com"]
}

update_event

Atualiza um evento existente.

{
  "eventId": "abc123xyz",
  "summary": "Reunião atualizada",
  "startTime": "2023-09-15T14:30:00Z",
  "endTime": "2023-09-15T15:30:00Z"
}

delete_event

Exclui um evento do calendário.

{
  "eventId": "abc123xyz"
}

find_free_time

Encontra horários disponíveis em um intervalo de tempo.

{
  "timeMin": "2023-09-01T00:00:00Z",
  "timeMax": "2023-09-30T23:59:59Z",
  "duration": 60
}

Obtendo um Refresh Token

Para obter um refresh token do Google, você pode usar o seguinte script:

const { google } = require('googleapis');
const http = require('http');
const url = require('url');
// Substituir com suas credenciais

const CLIENT_ID = 'seu-client-id';

const CLIENT_SECRET = 'seu-client-secret';

const REDIRECT_URI = 'http://localhost:3000/oauth2callback';
const oauth2Client = new google.auth.OAuth2(

  CLIENT_ID,

  CLIENT_SECRET,

  REDIRECT_URI

);
const scopes = [

  'https://www.googleapis.com/auth/calendar',

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

];
function getRefreshToken() {

  const server = http.createServer(async (req, res) => {

    const queryParams = url.parse(req.url, true).query;

    

    if (queryParams.code) {

      try {

        const { tokens } = await oauth2Client.getToken(queryParams.code);

        console.log('Refresh Token:', tokens.refresh_token);

        res.end('Autenticação bem-sucedida! Você pode fechar esta janela.');

        server.close();

      } catch (error) {

        console.error('Erro ao obter tokens:', error);

        res.end('Falha na autenticação!');

      }

    }

  }).listen(3000, () => {

    const authUrl = oauth2Client.generateAuthUrl({

      access_type: 'offline',

      scope: scopes,

      prompt: 'consent'

    });
console.log('Acesse esta URL no navegador:');

    console.log(authUrl);

  });

}
getRefreshToken();

Salve este script como getToken.js, execute-o com node getToken.js, e siga as instruções para obter seu refresh token.

Desenvolvimento

Para desenvolvimento, você pode executar:

npm run dev

Isso compilará o TypeScript em modo de observação, permitindo que você faça alterações e veja os resultados em tempo real.

Solução de Problemas

Problemas Comuns

1. Erro de autenticação no Google
- Verifique se suas credenciais estão corretas
- Confirme se o refresh token é válido
- Certifique-se de que os escopos necessários estão ativados

2. Servidor não inicia
- Verifique se todas as variáveis de ambiente estão definidas
- Confirme se o processo de build foi bem-sucedido
- Verifique as permissões do arquivo build/index.js

3. Conexão SSE falha
- Confirme se a porta (3334 por padrão) está disponível
- Verifique logs para erros específicos
- Certifique-se de que os endpoints estão corretamente configurados

Licença

ISC