Google Calendar MCP Server 🚀

The most comprehensive Model Context Protocol server for Google Calendar with 60+ advanced tools, resources, and prompts. Built on the Smithery TypeScript scaffold and the official MCP SDK.

GitHub: https://github.com/shade-solutions/calender-mcp
Smithery: https://smithery.ai/server/@shade-solutions/calender-mcp/

🌟 Features

Core Calendar Operations

• ✅ List and manage multiple calendars
• ✅ Create, read, update, and delete events
• ✅ Advanced event search and filtering
• ✅ Calendar sharing and ACL management
• ✅ Color customization and settings
• ✅ Guest permissions control

Advanced Scheduling

• 🚀 Event templates for quick creation
• 🚀 Working location events (office/home/custom)
• 🚀 Out of office and focus time blocking
• 🚀 Appointment slot generation with buffer time
• 🚀 Complex recurring events with exception dates
• 🚀 AI-powered optimal meeting time finder
• 🚀 Travel time calculation and automatic blocking
• 🚀 Smart scheduling based on preferences

Analytics & Insights

• 📊 Time allocation analysis by day/week/month
• 📊 Meeting effectiveness metrics
• 📊 Calendar utilization tracking
• 📊 Automatic event categorization (1:1s, interviews, sync, etc.)
• 📊 Pattern recognition and actionable recommendations
• 📊 Response rate tracking
• 📊 Back-to-back meeting detection

Batch Operations

• ⚡ Bulk create/update/delete events
• ⚡ Event duplication across multiple time slots
• ⚡ Search and replace across all events
• ⚡ Dry-run mode for safe testing
• ⚡ Error handling with detailed results

AI-Powered Features

• 🤖 Smart event suggestions from text/email
• 🤖 Conflict detection with resolution suggestions
• 🤖 Natural language event parsing
• 🤖 Intelligent meeting time recommendations
• 🤖 Event categorization and insights

Import/Export

• 📦 Export to JSON, CSV, and iCal formats
• 📦 Bulk event import
• 📦 Cross-calendar migration support

Availability Management

• 🗓️ Free/busy queries across calendars
• 🗓️ Mutual free time discovery
• 🗓️ Smart scheduling with working hours
• 🗓️ Weekend and holiday exclusions
• 🗓️ Preference-based time scoring

For a complete feature analysis and roadmap, see docs/comprehensive-google-calendar-mcp-features.md.

💡 Use Cases

• Executive Assistants & Scheduling: Automatically find optimal meeting times, manage multiple calendars, and handle complex scheduling with travel time
• Remote Teams: Set working locations, manage time zones, and find mutual availability across distributed teams
• Sales & Customer Success: Create appointment slots, manage client meetings, and track meeting effectiveness
• Recruiting & HR: Schedule interviews, avoid back-to-back meetings, and analyze calendar utilization
• Product & Engineering: Block focus time, analyze time allocation, and reduce meeting overhead with smart scheduling
• Consultants & Freelancers: Export billable hours, manage multiple client calendars, and automate recurring events
• Event Planners: Batch create events, duplicate series across time slots, and manage complex recurring schedules
• Analytics & Reporting: Generate time allocation reports, identify meeting patterns, and optimize team productivity

For detailed use cases with step-by-step examples, see USECASES.md.

Quick Start

Requirements:

• Node.js 18+
• Google Cloud Project with Calendar API enabled
• OAuth 2.0 credentials or Service Account

Installation:

git clone https://github.com/shade-solutions/calender-mcp.git
cd calender-mcp
npm install

Development:

npm run dev

Then connect a client to http://127.0.0.1:3000/mcp with configuration parameters (see Configuration below).

Production Build:

npm run build

Configuration

This server supports OAuth and Service Account authentication. Smithery auto-generates a config UI from the schema, or you can pass URL params.

Schema highlights (see src/config.ts):

• authMethod: oauth | service_account (default: oauth)
• oauth: clientId, clientSecret, redirectUri, accessToken, refreshToken
• serviceAccount: jsonKey (entire JSON as string), impersonatedUser (optional)
• defaultCalendarId (optional, default: "primary")
• debug (boolean, default: false)

Example Configurations

OAuth URL params (dot-notation):

http://127.0.0.1:3000/mcp?authMethod=oauth&oauth.clientId=YOUR_CLIENT_ID&oauth.clientSecret=YOUR_SECRET&oauth.refreshToken=YOUR_REFRESH_TOKEN&defaultCalendarId=primary

Service account example:

http://127.0.0.1:3000/mcp?authMethod=service_account&serviceAccount.jsonKey=%7B...escaped%20JSON...%7D&serviceAccount.impersonatedUser=user@yourdomain.com

Authentication Notes:

• OAuth is recommended for end users. Provide at least refreshToken for long-lived sessions.
• Service accounts require domain-wide delegation and scopes configured in the Google Admin console to impersonate users.

Complete Tools Reference (60+ Tools)

Basic Calendar Operations (9 tools)

• calendar.list_calendars — List all accessible calendars
• calendar.get — Get calendar details by ID
• calendars.insert — Create a new calendar
• calendars.update — Update calendar properties
• colors.get — Retrieve color definitions for events/calendars
• settings.list — List user calendar settings
• acl.list — List access control rules
• acl.insert — Add ACL rule (share calendar)
• acl.delete — Remove ACL rule

Event Management (10 tools)

• events.list — List events with advanced filters (time range, search query, max results)
• events.get — Get a single event by ID
• events.create — Create event with full options (attendees, reminders, recurrence, conference)
• events.update — Update event fields
• events.delete — Delete event
• events.quickAdd — Create event from natural language text
• events.move — Move event between calendars
• events.instances — List instances of a recurring event
• events.rsvp — Set attendee response status

Advanced Scheduling (7 tools)

• templates.create_from_template — Create events from predefined templates
• events.set_working_location — Set working location (office/home/custom)
• events.set_out_of_office — Block calendar for out of office with auto-decline
• events.set_focus_time — Schedule focus time blocks
• scheduling.create_appointment_slots — Generate appointment booking slots
• events.create_recurring_with_exceptions — Create recurring events with exception dates
• scheduling.find_optimal_time — Find best meeting time with AI scoring

Availability Tools (2 tools)

• freebusy.query — Query free/busy status across calendars
• availability.find_mutual_free_times — Find mutual free time slots with constraints

Analytics Tools (4 tools)

• analytics.time_analysis — Analyze time allocation with metrics and insights
• analytics.meeting_effectiveness — Analyze meeting patterns and effectiveness
• analytics.calendar_utilization — Calculate calendar utilization percentage
• analytics.categorize_events — Automatically categorize events by type

Batch Operations (5 tools)

• batch.create_events — Bulk create multiple events
• batch.delete_events — Bulk delete multiple events
• batch.update_events — Bulk update multiple events with same changes
• batch.duplicate_event_series — Duplicate event to multiple time slots
• batch.search_and_replace — Search and replace text across events (with dry-run)

Integration Tools (4 tools)

• export.events_to_format — Export events to JSON/CSV/iCal
• ai.suggest_event_from_text — Parse text/email and suggest event details
• calendar.block_travel_time — Add travel time blocks before/after events
• calendar.detect_conflicts — Detect scheduling conflicts with resolution suggestions

Authentication (2 tools)

• auth.generate_auth_url — Generate OAuth consent URL
• auth.exchange_code — Exchange authorization code for tokens

Resources

Dynamic, queryable resources that provide calendar data:

• gcal://events?calendarId=...&timeMin=...&timeMax=... — Returns events list JSON
• gcal://event?calendarId=...&eventId=... — Returns single event JSON

See src/resources/gcal.ts for implementation details.

Prompts

Interactive prompts to guide users through complex workflows:

• schedule_meeting — Step-by-step guide to find mutual time and schedule meetings
• reschedule_meeting — Guide for rescheduling with automatic attendee notifications

See src/prompts/scheduling.ts for implementation details.

Usage Examples

Initialize Session

curl -X POST "http://127.0.0.1:3000/mcp?debug=true" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"clientInfo":{"name":"test","version":"1.0.0"}}}'

List Events

curl -X POST "http://127.0.0.1:3000/mcp?..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"events.list","arguments":{"calendarId":"primary","singleEvents":true,"timeMin":"2025-01-01T00:00:00Z","timeMax":"2025-01-31T23:59:59Z"}}}'

Create Event with Template

curl -X POST "http://127.0.0.1:3000/mcp?..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"templates.create_from_template","arguments":{"templateName":"standup","summary":"Daily Standup","durationMinutes":15,"calendarId":"primary","startDateTime":"2025-01-10T09:00:00Z"}}}'

Find Optimal Meeting Time

curl -X POST "http://127.0.0.1:3000/mcp?..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"scheduling.find_optimal_time","arguments":{"calendars":["primary","colleague@example.com"],"timeMin":"2025-01-10T09:00:00Z","timeMax":"2025-01-10T18:00:00Z","durationMinutes":60,"avoidEarlyMorning":true}}}'

Analyze Calendar Utilization

curl -X POST "http://127.0.0.1:3000/mcp?..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"analytics.calendar_utilization","arguments":{"calendarId":"primary","startDate":"2025-01-01","endDate":"2025-01-31"}}}'

Batch Create Appointment Slots

curl -X POST "http://127.0.0.1:3000/mcp?..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"scheduling.create_appointment_slots","arguments":{"calendarId":"primary","startDate":"2025-01-13","endDate":"2025-01-17","slotDurationMinutes":30,"bufferMinutes":5,"workingHoursStart":"09:00","workingHoursEnd":"17:00","excludeWeekends":true}}}'

Development

Project Structure

src/
├── tools/
│   ├── calendar/
│   │   └── basic.ts          # Basic calendar operations
│   ├── events.ts              # Event management
│   ├── availability.ts        # Free/busy and availability
│   ├── advanced-scheduling.ts # Advanced scheduling features
│   ├── analytics.ts           # Analytics and insights
│   ├── batch-operations.ts    # Bulk operations
│   ├── integrations.ts        # Integrations and exports
│   └── auth.ts                # Authentication tools
├── auth/
│   └── google.ts              # Google OAuth/Service Account
├── utils/
│   └── schemas.ts             # Zod validation schemas
├── resources/
│   └── gcal.ts                # Dynamic resources
├── prompts/
│   └── scheduling.ts          # Interactive prompts
├── config.ts                  # Configuration schema
└── index.ts                   # Main server entry

Best Practices Used

• Type Safety: Full TypeScript with Zod validation
• Error Handling: Comprehensive error catching in batch operations
• Dry-Run Support: Safe testing mode for destructive operations
• Extensible Architecture: Modular tool registration system
• Input Validation: Zod schemas for all tool inputs
• Comprehensive Logging: Debug mode with detailed output
• RESTful Design: Consistent naming and patterns
• Documentation: JSDoc comments and detailed README

Adding New Tools

1. Create a new file in src/tools/ (e.g., my-feature.ts)
2. Define Zod schemas in src/utils/schemas.ts
3. Implement tool registration function:

import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { z } from "zod"
import type { ServerConfig } from "../config.js"

export function registerMyFeature(server: McpServer, config: ServerConfig) {
  server.registerTool(
    "my.tool_name",
    {
      title: "My Tool",
      description: "Description of what it does",
      inputSchema: {
        param1: z.string(),
        param2: z.number().optional(),
      },
    },
    async (args: any) => {
      // Implementation
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      }
    }
  )
}

4. Register in src/index.ts:

import { registerMyFeature } from "./tools/my-feature.js"
// ...
registerMyFeature(server, config)

Security and Privacy

• ✅ No secrets are persisted by the server
• ✅ Client passes config per session
• ✅ OAuth tokens are refreshed automatically
• ✅ Service account keys are never logged
• ✅ Prefer using refresh tokens over access tokens
• ✅ Consider gateway/OAuth via Smithery for production
• ✅ Supports domain-wide delegation for service accounts

Security Best Practices:

1. Never commit credentials to version control
2. Use environment variables for sensitive data
3. Implement least-privilege scopes
4. Rotate service account keys regularly
5. Monitor OAuth token usage
6. Use HTTPS in production environments

Roadmap

Planned enhancements aligned with docs/comprehensive-google-calendar-mcp-features.md:

Phase 1 (Completed ✅)

• ✅ Advanced scheduling features
• ✅ Analytics and insights
• ✅ Batch operations
• ✅ AI-powered features
• ✅ Integration tools

Phase 2 (In Progress)

• 🔄 Video conference integration (Zoom, Teams, Meet)
• 🔄 Slack notifications
• 🔄 CRM system sync
• 🔄 Payment processing for appointments
• 🔄 Multi-language support

Phase 3 (Planned)

• 📋 Advanced RBAC and permissions
• 📋 Audit logs and compliance reporting
• 📋 Real-time collaboration features
• 📋 Mobile app integration
• 📋 Custom dashboards

Contributing

Contributions are welcome! This project follows best practices for open-source contributions:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Contribution Guidelines:

• Follow TypeScript best practices
• Add Zod validation for all inputs
• Include JSDoc comments for functions
• Write comprehensive error handling
• Test with both OAuth and Service Account auth
• Update documentation for new features

License

ISC License - see LICENSE file for details

Support

• GitHub Issues: https://github.com/shade-solutions/calender-mcp/issues
• Documentation: See docs/ folder for comprehensive guides
• Smithery: https://smithery.ai/server/@shade-solutions/calender-mcp/

Acknowledgments

• Built with Smithery TypeScript scaffold
• Powered by MCP SDK
• Uses Google Calendar API v3
• Community feedback from 100+ calendar integration implementations

---

Made with ❤️ by the open-source community

⭐ If you find this useful, please star the repository!