calender-mcp

shade-solutions/calender-mcp

3.3

If you are the rightful owner of calender-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Google Calendar MCP Server is a production-grade Model Context Protocol server designed for Google Calendar, offering a comprehensive suite of tools, resources, and prompts.

Tools
3
Resources
0
Prompts
0

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 .

šŸ’” 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 .

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) }],
      }
    }
  )
}
  1. 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 :

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

Acknowledgments

Made with ā¤ļø by the open-source community

ā­ If you find this useful, please star the repository!