What is Mcp Google Calendar Server

mcp-google-calendar-server is an implementation of the Model Context Protocol (MCP) for Google Calendar, enabling interaction with calendar events through CLI or Server-Sent Events (SSE).

Use cases

Use cases include automating event scheduling, integrating calendar functionalities into desktop applications, and providing real-time updates on calendar events through SSE.

How to use

To use mcp-google-calendar-server, set up your environment by copying the ‘.env.example’ file to ‘.env’, configure your Google OAuth 2.0 credentials, install dependencies with ‘npm install’, and compile the code with ‘npm run build’. You can run the server either as an HTTP/SSE server or in CLI mode.

Key features

Key features include listing calendar events, creating new events, updating existing events, deleting events, and finding available time slots.

Where to use

mcp-google-calendar-server can be used in applications that require calendar event management, such as personal productivity tools, scheduling applications, and collaborative platforms.

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": [
    "[email protected]",
    "[email protected]"
  ]
}

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