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.

- 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

- 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

- 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

- 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

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

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

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

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

- Go toGoogle Cloud Console
- Create a new project or select existing
- Enable the Google Calendar API
- Create OAuth 2.0 credentials
- Add your credentials to.env

# Start PostgreSQL and Redis (using Docker) docker-compose up -d postgres redis # Or install locally and create database createdb calendar_assistant

npm run build npm start # Or for development npm run dev

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

// 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"

// AI Assistant can process: "When are we all free next week for a 2-hour workshop?" "Find time for a 30-minute call with the marketing team" "What's my availability on Friday afternoon?"

// AI Assistant can process: "Remind me to call mom this weekend" "Add a high-priority task to review the Q4 budget by Friday" "Show me all my overdue tasks"

{ "mcpServers": { "calendar-assistant": { "command": "node", "args": ["/path/to/mcp-calendar-server/dist/index.js"], "env": { "DATABASE_URL": "postgresql://localhost:5432/calendar_assistant", "GOOGLE_CLIENT_ID": "your-client-id", "GOOGLE_CLIENT_SECRET": "your-client-secret" } } } }

import { CalendarMCPServer } from 'mcp-calendar-server'; const server = new CalendarMCPServer(); await server.start();

# Configure environment cp .env.example .env # Edit .env with your settings # Start all services docker-compose up -d # Check logs docker-compose logs -f mcp-calendar-server

# Build production image docker build -f docker/Dockerfile -t mcp-calendar-server . # Run with external database docker run -d \ --name calendar-server \ -p 3000:3000 \ -e DATABASE_URL="postgresql://user:pass@host:5432/db" \ -e REDIS_URL="redis://host:6379" \ -e GOOGLE_CLIENT_ID="your-id" \ -e GOOGLE_CLIENT_SECRET="your-secret" \ mcp-calendar-server

- JWT-based session management
- OAuth 2.0 with Google Calendar
- Secure token refresh handling
- Session cleanup and expiration

- Environment variable encryption
- Database connection encryption
- API rate limiting
- Input validation and sanitization

- Non-root container execution
- Minimal attack surface
- Regular security updates
- Audit logging

# Check server health curl http://localhost:3000/health # Check database connectivity curl http://localhost:3000/health/db # Check cache connectivity curl http://localhost:3000/health/cache

Structured JSON logging with configurable levels:

- Error tracking and alerting
- Performance metrics
- Security event logging
- Debug information for development
- Fork the repository
- Create a feature branch (git checkout -b feature/amazing-feature)
- Commit your changes (git commit -m 'Add amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

# Install dependencies npm install # Run tests npm test # Run linter npm run lint # Format code npm run format # Start development server npm run dev

- ✅ Google Calendar integration
- ✅ Basic CRUD operations
- ✅ Free time finding
- ✅ Task management
- ✅ Caching layer

- 🔄 Outlook Calendar integration
- 🔄 Advanced scheduling algorithms
- 🔄 Natural language time parsing
- 🔄 Webhook support for real-time updates

- 📅 Apple Calendar integration
- 📅 CalDAV support
- 📅 Meeting room booking
- 📅 Travel time integration
- 📅 Smart conflict resolution

- 🔮 Machine learning insights
- 🔮 Predictive scheduling
- 🔮 Integration with other productivity tools
- 🔮 Mobile app companion

This project is licensed under the MIT License - see theLICENSEfile for details.

- Model Context Protocolby Anthropic
- Google Calendar API
- PostgreSQLfor reliable data storage
- Redisfor high-performance caching

- 📧 Email:support@example.com
- 💬 Discord:Join our community
- 📖 Documentation:docs.example.com
- 🐛 Issues:GitHub Issues

Remote MCP server for MeisterTask. Create and manage projects, tasks, and notes from your AI assistant. Hosted (streamable-HTTP) — connect at https://mcp.meistertask.com/mcp