mcp-server-example

felipeandrademorais/mcp-server-example

3.1

If you are the rightful owner of mcp-server-example and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This project is an MCP server that integrates with the Google Calendar API to fetch and return calendar events by date.

Tools
1
Resources
0
Prompts
0

MCP Server Example - Google Calendar Integration

Um servidor MCP (Model Context Protocol) que integra com o Google Calendar API para buscar e retornar eventos do calendário por data.

📋 Índice

🎯 Sobre o Projeto

Este projeto implementa um servidor MCP que permite acessar dados do Google Calendar através do Model Context Protocol. O servidor fornece uma ferramenta (getMyCalendarDataByDate) que busca eventos do calendário para uma data específica, filtrando automaticamente eventos relacionados a "Home" e retornando uma lista formatada de reuniões.

✨ Funcionalidades

  • Busca de Eventos por Data: Recupera todos os eventos de um calendário específico para uma data fornecida
  • Filtro Automático: Remove automaticamente eventos que contenham "Home" no título
  • Formatação de Dados: Retorna eventos formatados com título e horário de início
  • Validação de Entrada: Valida o formato da data usando Zod
  • Tratamento de Erros: Retorna mensagens de erro estruturadas em caso de falhas

🔧 Pré-requisitos

Antes de começar, certifique-se de ter instalado:

  • Node.js (versão 18 ou superior)
  • npm ou yarn
  • Uma conta Google com acesso à Google Calendar API
  • Uma chave de API do Google (API Key pública)
  • O ID do calendário que deseja acessar

📦 Instalação

  1. Clone o repositório ou navegue até o diretório do projeto:
cd mcp-server-example
  1. Instale as dependências:
npm install

⚙️ Configuração

1. Obter Credenciais do Google

  1. Acesse o Google Cloud Console
  2. Crie um novo projeto ou selecione um existente
  3. Ative a Google Calendar API para o seu projeto
  4. Vá para Credenciais e crie uma Chave de API (API Key)
  5. Copie a chave de API gerada

2. Obter o ID do Calendário

O ID do calendário é seu E-mail Google

3. Configurar Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

GOOGLE_PUBLIC_API_KEY=sua_chave_api_aqui
CALENDAR_ID=seu_email_google

🚀 Uso

Executar o Servidor

Para iniciar o servidor MCP:

npm start

Ou em modo de desenvolvimento (com watch):

npm run dev

Como Funciona

O servidor MCP é executado via stdio (entrada/saída padrão) e aguarda requisições do cliente MCP. Ele expõe a ferramenta getMyCalendarDataByDate que pode ser chamada através de um cliente MCP compatível.

🎨 Integração com Cursor

Abra o arquivo de configuração do MCP e adicione a seguinte configuração:

{
  "mcpServers": {
    "mcp-server-example": {
      "command": "npx",
      "args": [
       "tsx",
        "/caminho/absoluto/para/o/projeto/index.ts"
      ],
      "env": {
        "GOOGLE_PUBLIC_API_KEY": "sua_chave_api_aqui",
        "CALENDAR_ID": "seu_email_google"
      }
    }
  }
}

Após salvar o arquivo de configuração, reinicie o Cursor completamente para que as mudanças tenham efeito.

📁 Estrutura do Projeto

mcp-server-example/
├── index.ts              # Arquivo principal do servidor MCP
├── package.json          # Dependências e scripts do projeto
├── package-lock.json     # Lock file das dependências
├── .env                  # Variáveis de ambiente (não versionado)
├── .env.example          # Exemplo de variáveis de ambiente
├── .gitignore           # Arquivos ignorados pelo Git
└── README.md            # Documentação do projeto

📚 Dependências

Dependências Principais

  • @modelcontextprotocol/sdk (^1.21.0): SDK oficial do Model Context Protocol para Node.js
  • googleapis (^164.1.0): Cliente oficial do Google APIs para Node.js
  • zod (^3.25.76): Biblioteca de validação de esquemas TypeScript-first
  • dotenv (^17.2.3): Carrega variáveis de ambiente de arquivos .env

Dependências de Desenvolvimento

  • @types/node (^24.10.0): Definições de tipos TypeScript para Node.js

📜 Scripts Disponíveis

  • npm start: Executa o servidor usando tsx
  • npm run dev: Executa o servidor em modo watch (reinicia automaticamente em mudanças)

🔌 API e Ferramentas

Ferramenta: getMyCalendarDataByDate

Busca eventos do calendário para uma data específica.

Parâmetros
  • date (string, obrigatório): Data no formato ISO 8601 ou qualquer formato válido reconhecido por Date.parse()
Retorno

O retorno é um objeto JSON com a seguinte estrutura:

Sucesso:

{
  "meetings": [
    "Reunião de Equipe at 2024-01-15T10:00:00-03:00",
    "Almoço com Cliente at 2024-01-15T12:30:00-03:00"
  ]
}

Sem eventos:

{
  "meetings": []
}

Erro:

{
  "error": "Mensagem de erro aqui"
}

🔗 Links Úteis