MCP Calendar Assistant

# MCP Calendar Server - Installation Guide ## 🎯 What's Been Built Your MCP Calendar Server is now ready! Here's what you have: ### 🏗️ Complete Architecture - **MCP Server**: Fully functional Model Context Protocol server - **Google Calendar Integration**: OAuth2-based calendar access - **Task Management**: Full CRUD operations for reminders/tasks - **Smart Scheduling**: AI-powered meeting suggestions and free time finding - **Caching Layer**: Redis-powered performance optimization - **Database Layer**: PostgreSQL with comprehensive schema - **Docker Support**: Container deployment ready ### 📁 Project Structure ``` mcp-calendar-server/ ├── src/ │ ├── index.ts # Main MCP server entry point │ ├── types.ts # TypeScript type definitions │ ├── tools/ # MCP tool implementations │ │ └── CalendarTools.ts # All 15+ calendar tools │ ├── services/ # Business logic layer │ │ ├── CalendarService.ts │ │ └── ReminderService.ts │ ├── providers/ # Calendar API integrations │ │ ├── CalendarProvider.ts │ │ └── GoogleCalendarProvider.ts │ ├── database/ # Database management │ │ └── index.ts # PostgreSQL with full schema │ ├── cache/ # Caching implementation │ │ └── index.ts # Redis + in-memory fallback │ └── config/ # Configuration management │ └── index.ts # Environment-based config ├── docker/ # Docker deployment files ├── package.json # Dependencies and scripts ├── docker-compose.yml # Full stack deployment ├── .env.example # Configuration template └── README.md # Comprehensive documentation ``` ### 🛠️ Available Tools (15 Total) **Calendar Operations:** - `get_calendars` - List user's calendars - `get_calendar_events` - Retrieve events with filtering - `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 attendee availability - `suggest_meeting_times` - AI-powered scheduling **Task Management:** - `create_reminder` - Create tasks/reminders - `get_reminders` - Retrieve with filtering - `update_reminder` - Modify tasks - `complete_reminder` - Mark as done **Intelligence & Analytics:** - `analyze_schedule_patterns` - Schedule insights - `get_working_hours` - User preferences - `get_recent_similar_events` - Context finding - `get_contact_suggestions` - Auto-complete contacts ## 🚀 Quick Start ### 1. Make Setup Script Executable ```bash cd /Users/mohammedomer/Documents/mcp-calendar-server chmod +x setup.sh ``` ### 2. Run Setup ```bash ./setup.sh ``` ### 3. Configure Environment Edit `.env` with your settings: ```bash # Required: Google Calendar API credentials GOOGLE_CLIENT_ID=your_client_id_here GOOGLE_CLIENT_SECRET=your_client_secret_here # Required: Secure JWT secret JWT_SECRET=generate_a_secure_random_string_here # Optional: Database (defaults to Docker) DATABASE_URL=postgresql://localhost:5432/calendar_assistant REDIS_URL=redis://localhost:6379 ``` ### 4. Get Google Calendar Credentials 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Create/select project 3. Enable Calendar API 4. Create OAuth 2.0 credentials 5. Set redirect URI: `http://localhost:3000/auth/google/callback` 6. Copy Client ID and Secret to `.env` ### 5. Start the Server ```bash # Start database services (if using Docker) docker-compose up -d postgres redis # Build and start the MCP server npm run build npm start ``` ## 🔌 Connect to Claude Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "calendar-assistant": { "command": "node", "args": ["/Users/mohammedomer/Documents/mcp-calendar-server/dist/index.js"], "env": { "DATABASE_URL": "postgresql://localhost:5432/calendar_assistant", "REDIS_URL": "redis://localhost:6379", "GOOGLE_CLIENT_ID": "your-google-client-id", "GOOGLE_CLIENT_SECRET": "your-google-client-secret", "JWT_SECRET": "your-jwt-secret-key" } } } } ``` ## 💬 Usage Examples Once connected to Claude, you can say: ### Calendar Management - "Schedule a dentist appointment next Tuesday at 2pm" - "Find a 2-hour slot next week when John, Sarah, and I are all free" - "What meetings do I have tomorrow?" - "Cancel my 3pm meeting on Friday" ### Smart Scheduling - "When are the best times for a team meeting next week?" - "Check if everyone is available Thursday afternoon" - "Find time for a 30-minute call with the marketing team" ### Task Management - "Remind me to call mom this weekend" - "Add reviewing the Q4 budget as a high-priority task due Friday" - "Show me all my overdue tasks" - "Mark the project review task as completed" ### Analytics & Insights - "How busy have I been this month?" - "Who do I meet with most often?" - "What are my typical working hours?" - "Find similar events to 'project review'" ## 🎯 Key Features ### Intelligent Parsing The server handles natural language input and converts it to structured calendar operations. No need to specify exact parameters - just describe what you want in plain English. ### Performance Optimized - **Caching**: Frequently accessed data cached in Redis - **Batching**: Multiple operations combined for efficiency - **Smart Prefetching**: Anticipates data needs ### Production Ready - **Authentication**: Secure OAuth2 + JWT - **Rate Limiting**: API protection - **Error Handling**: Graceful failure recovery - **Logging**: Comprehensive monitoring - **Docker**: Container deployment ### Extensible Architecture - **Provider Pattern**: Easy to add Outlook, Apple Calendar - **Modular Design**: Services, tools, and providers are decoupled - **Configuration**: Environment-based feature flags ## 🔧 Development ### Adding New Tools 1. Define tool schema in `CalendarTools.ts` 2. Implement handler method 3. Add business logic to appropriate service 4. Update documentation ### Adding New Providers 1. Extend `CalendarProvider` abstract class 2. Implement all abstract methods 3. Add to `ProviderFactory` 4. Update configuration ### Running Tests ```bash npm test ``` ### Development Mode ```bash npm run dev # Auto-restart on changes ``` ## 🎉 You're All Set! Your MCP Calendar Server is a production-ready system that brings intelligent calendar management to AI assistants. The architecture is designed to scale and can easily be extended with additional calendar providers, new tools, and enhanced AI capabilities. **Next Steps:** 1. Run the setup script 2. Configure your Google Calendar API 3. Start the server 4. Connect to Claude 5. Start managing your calendar with natural language! The server is built with TypeScript, follows best practices, and includes comprehensive error handling, caching, and monitoring. You now have a powerful tool that transforms how AI assistants interact with calendar systems.