teren-papercutlabs/gcal-mcp

Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Google Calendar integration. This server allows LLMs to manage calendar events, handle attendees, and work with recurring events through the MCP protocol.

Features

• 📅 Calendar Management: List and access multiple calendars
• 📝 Event Operations: Create, read, update, and delete events
• 🔍 Smart Search: Search events by text across all fields
• 👥 Attendee Management: Add and manage event attendees
• 🔁 Recurring Events: Full support for recurring event patterns
• 🌏 Timezone Handling: Default Singapore timezone with proper conversions
• 🔐 OAuth 2.0: Secure authentication with Google

Installation

1. Clone the repository:

git clone https://github.com/teren-papercutlabs/gcal-mcp.git
cd gcal-mcp

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Setup

1. Google Cloud Console Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   • Go to "APIs & Services" > "Enable APIs and services"
   • Search for "Google Calendar API"
   • Click "Enable"

2. Create OAuth 2.0 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. Choose "Desktop app" as the application type
4. Name it (e.g., "Calendar MCP")
5. Download the credentials JSON file
6. Save it as credentials.json in the root of this project

3. Configure MCP

Add to your MCP configuration file (.mcp.json):

{
  "mcpServers": {
    "gcal": {
      "command": "node",
      "args": ["/path/to/gcal-mcp/dist/index.js"],
      "cwd": "/path/to/gcal-mcp"
    }
  }
}

4. First Run

On first use, the server will:

1. Open your browser for Google OAuth authentication
2. Ask you to grant calendar permissions
3. Save the authentication token for future use

Available Tools

gcal_list_calendars

List all accessible Google Calendars. Returns calendar IDs and metadata.

gcal_list_events

List events within a date range. Defaults to next 7 days from primary calendar.

gcal_search_events

Search for events by text query across all event fields.

gcal_create_event

Create a new calendar event with optional attendees and recurrence rules.

gcal_update_event

Update an existing event. Supports partial updates and recurring event modifications.

gcal_delete_event

Delete an event. For recurring events, can delete single instance or entire series.

gcal_get_event

Get detailed information about a specific event.

Usage Examples

Create a Simple Event

Create a meeting tomorrow at 2pm called "Team Standup"

Create a Recurring Event

Schedule a weekly team meeting every Monday at 10am starting next week

Search for Events

Find all meetings with John next week

Update an Event

Move tomorrow's team standup to 3pm

Delete an Event

Cancel the team meeting on Friday

Time Format

All times use Singapore timezone (UTC+8) by default. Supported formats:

• YYYY-MM-DD HH:mm:ss (e.g., "2024-01-15 14:30:00")
• ISO 8601 format also accepted

Recurrence Rules

Uses standard RRULE format. Common patterns:

• Daily: RRULE:FREQ=DAILY
• Weekly on specific days: RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
• Monthly on date: RRULE:FREQ=MONTHLY;BYMONTHDAY=15
• With end date: RRULE:FREQ=DAILY;UNTIL=20240131

Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Run built version
npm start

Security

• credentials.json and token.json contain sensitive data
• Never commit these files to version control
• The .gitignore file excludes them by default

License

MIT