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
- Go to Google Cloud Console
- Create a new project or select existing
- Enable the Google Calendar API
- Create OAuth 2.0 credentials
- 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
| Variable | Description | Default |
|---|---|---|
DATABASE_URL | PostgreSQL connection string | postgresql://localhost:5432/calendar_assistant |
REDIS_URL | Redis connection string | redis://localhost:6379 |
GOOGLE_CLIENT_ID | Google OAuth client ID | Required |
GOOGLE_CLIENT_SECRET | Google OAuth client secret | Required |
JWT_SECRET | Secret for JWT tokens | Required |
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 calendarsget_calendar_events- Retrieve events from a calendarcreate_calendar_event- Create new eventsupdate_calendar_event- Modify existing eventsdelete_calendar_event- Remove eventsfind_free_time- Find available time slotscheck_availability- Check if people are freesuggest_meeting_times- AI-powered meeting suggestions
Task Management
create_reminder- Create tasks and remindersget_reminders- Retrieve tasks with filteringupdate_reminder- Modify existing taskscomplete_reminder- Mark tasks as completed
Analytics & Insights
analyze_schedule_patterns- Understand scheduling habitsget_working_hours- Retrieve work schedule preferencesget_recent_similar_events- Find related eventsget_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 workshop?"
"Find time for a 30-minute call with the marketing team"
"What's my availability on Friday afternoon?"
Task Management
// 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"
🔌 MCP Integration
With Claude Desktop
Add to your claude_desktop_config.json:
{
"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"
}
}
}
}
With Custom Applications
import { CalendarMCPServer } from 'mcp-calendar-server';
const server = new CalendarMCPServer();
await server.start();
🐳 Docker Deployment
Using Docker Compose
# 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
Production Deployment
# 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
🔒 Security
Authentication
- JWT-based session management
- OAuth 2.0 with Google Calendar
- Secure token refresh handling
- Session cleanup and expiration
Data Protection
- Environment variable encryption
- Database connection encryption
- API rate limiting
- Input validation and sanitization
Best Practices
- Non-root container execution
- Minimal attack surface
- Regular security updates
- Audit logging
📊 Monitoring
Health Checks
# 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
Logging
Structured JSON logging with configurable levels:
- Error tracking and alerting
- Performance metrics
- Security event logging
- Debug information for development
🤝 Contributing
- 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
Development Setup
# Install dependencies
npm install
# Run tests
npm test
# Run linter
npm run lint
# Format code
npm run format
# Start development server
npm run dev
🗺️ Roadmap
Phase 1 (Current)
- ✅ Google Calendar integration
- ✅ Basic CRUD operations
- ✅ Free time finding
- ✅ Task management
- ✅ Caching layer
Phase 2 (In Progress)
- 🔄 Outlook Calendar integration
- 🔄 Advanced scheduling algorithms
- 🔄 Natural language time parsing
- 🔄 Webhook support for real-time updates
Phase 3 (Planned)
- 📅 Apple Calendar integration
- 📅 CalDAV support
- 📅 Meeting room booking
- 📅 Travel time integration
- 📅 Smart conflict resolution
Phase 4 (Future)
- 🔮 Machine learning insights
- 🔮 Predictive scheduling
- 🔮 Integration with other productivity tools
- 🔮 Mobile app companion
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Model Context Protocol by Anthropic
- Google Calendar API
- PostgreSQL for reliable data storage
- Redis for high-performance caching
📞 Support
- 📧 Email: support@example.com
- 💬 Discord: Join our community
- 📖 Documentation: docs.example.com
- 🐛 Issues: GitHub Issues
Made with ❤️ for the MCP community