MCP Calendar Assistant MCP Server

MCP Calendar Assistant

A powerful Model Context Protocol (MCP) server that provides intelligent calendar and task management capabilities. This server allows AI assistants to interact with your calendar through natural language, handling everything from simple event creation to complex scheduling analysis.

🌟 Features

Core Calendar Operations

• Multi-Calendar Support: Google Calendar (with Outlook/Apple Calendar planned)
• Event Management: Create, read, update, delete calendar events
• Smart Scheduling: Find free time slots across multiple calendars
• Availability Checking: Check if people are available for meetings
• Meeting Suggestions: AI-powered optimal meeting time recommendations

Task & Reminder Management

• Smart Reminders: Create and manage tasks with priorities and due dates
• Natural Language: Process tasks from unstructured text input
• Analytics: Track completion rates and productivity patterns

Intelligence Features

• Schedule Analysis: Understand your scheduling patterns and habits
• Contact Suggestions: Auto-suggest frequent collaborators
• Similar Events: Find related events for context
• Working Hours: Respect user preferences and constraints

Performance & Reliability

• Intelligent Caching: Redis-powered caching with configurable TTLs
• Batch Operations: Efficient bulk calendar operations
• Error Handling: Robust error recovery and retry mechanisms
• Rate Limiting: Built-in protection against API abuse

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │────│  MCP Calendar    │────│  Calendar APIs  │
│   (Claude, etc) │    │     Server       │    │ (Google, etc)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                       ┌──────────────────┐
                       │  PostgreSQL +    │
                       │     Redis        │
                       └──────────────────┘

🚀 Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL 12+
• Redis 6+ (optional but recommended)
• Google Cloud Project with Calendar API enabled

1. Clone and Install

git clone <repository-url>
cd mcp-calendar-server
npm install

2. Environment Setup

cp .env.example .env
# Edit .env with your configuration

3. Google Calendar Setup

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the Google Calendar API
4. Create OAuth 2.0 credentials
5. Add your credentials to .env

4. Database Setup

# Start PostgreSQL and Redis (using Docker)
docker-compose up -d postgres redis

# Or install locally and create database
createdb calendar_assistant

5. Build and Start

npm run build
npm start

# Or for development
npm run dev

🔧 Configuration

Environment Variables

Feature Flags

FEATURE_CACHING=true          # Enable Redis caching
FEATURE_BATCHING=true         # Enable batch operations
FEATURE_PREFETCHING=true      # Enable predictive data loading
FEATURE_ANALYTICS=false       # Enable usage analytics
FEATURE_MULTI_PROVIDER=false  # Enable multiple calendar providers

📋 Available Tools

Calendar Operations

• get_calendars - List available calendars
• get_calendar_events - Retrieve events from a calendar
• create_calendar_event - Create new events
• update_calendar_event - Modify existing events
• delete_calendar_event - Remove events
• find_free_time - Find available time slots
• check_availability - Check if people are free
• suggest_meeting_times - AI-powered meeting suggestions

Task Management

• create_reminder - Create tasks and reminders
• get_reminders - Retrieve tasks with filtering
• update_reminder - Modify existing tasks
• complete_reminder - Mark tasks as completed

Analytics & Insights

• analyze_schedule_patterns - Understand scheduling habits
• get_working_hours - Retrieve work schedule preferences
• get_recent_similar_events - Find related events
• get_contact_suggestions - Auto-suggest contacts

💬 Usage Examples

Creating Events

// AI Assistant can process:
"Schedule a dentist appointment next Tuesday at 2pm"
"Book a team meeting with John and Sarah for next week, 1 hour duration"
"Create a recurring weekly standup every Monday at 9am"

Finding Free Time

// AI Assistant can process:
"When are we all free next week for a 2-hour wo