Google Calendar MCP Server

This is a Model Context Protocol (MCP) server that provides integration with Google Calendar. It allows LLMs to read, create, and manage calendar events through a standardized interface.

Features

• List available calendars
• List events from a calendar
• Create new calendar events with rich formatting
• Update existing events
• Delete events
• Process events from screenshots and images
• Automatic token refresh and authentication

Requirements

• Node.js 16 or higher
• TypeScript 5.3 or higher
• A Google Cloud project with the Calendar API enabled
• OAuth 2.0 credentials (Client ID and Client Secret)
• Bun (optional, for improved performance)

Project Structure

google-calendar-mcp/
├── src/           # TypeScript source files
│   ├── index.ts         # Main server implementation
│   ├── auth-server.ts   # OAuth authentication server
│   └── token-manager.ts # Token management and refresh
├── build/         # Compiled JavaScript output
├── llm/           # LLM-specific configurations and prompts
├── package.json   # Project dependencies and scripts
└── tsconfig.json  # TypeScript configuration

Google Cloud Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one.
3. Enable the Google Calendar API.
4. Create OAuth 2.0 credentials:
   • Go to Credentials
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "User data" as the type of data the app will be accessing.
   • Add your app name and contact information.
   • Add the following scope:
     • https://www.googleapis.com/auth/calendar (full access to calendars)
     • Or for more limited access: https://www.googleapis.com/auth/calendar.events (manage events only)
   • Select "Desktop app" as the application type.
   • Add your email address as a test user under the OAuth Consent screen.
     • Note: It may take a few minutes for the test user to propagate.
5. Download the credentials JSON file and rename it to gcp-oauth.keys.json

Installation

1. Clone the repository:

   git clone https://github.com/pashpashpash/google-calendar-mcp.git
   cd google-calendar-mcp
   

2. Install dependencies:

   npm install
   

   Or with Bun:

   bun install
   

3. Build the TypeScript code:

   npm run build
   

   Or with Bun:

   bun build src/index.ts --outdir build --target node
   bun build src/auth-server.ts --outdir build --target node
   bun build src/token-manager.ts --outdir build --target node
   

4. Download your Google OAuth credentials from the Google Cloud Console.

   • Rename the file to gcp-oauth.keys.json
   • Place it in the root directory of the project.

5. Run the server:

   npm start
   

   Or with Bun:

   bun build/index.js
   

Available Scripts

• npm run build - Build the TypeScript code.
• npm run build:watch - Build TypeScript in watch mode for development.
• npm run dev - Start the server in development mode using ts-node.
• npm run auth - Start the authentication server for Google OAuth flow.

Authentication Setup

Automatic Authentication (Recommended)

1. Ensure your OAuth credentials are in gcp-oauth.keys.json
2. Start the MCP server:

   npm start
   

3. If no authentication tokens are found, the server will:
   • Start an authentication server (on ports 3000-3004).
   • Open a browser window for OAuth authentication.
   • Save the authentication tokens securely.
   • Shut down the authentication server and continue normal operation.

Manual Authentication

If you prefer to manually authenticate, run:

npm run auth

• This starts an authentication server, opens a browser for OAuth, and saves the tokens.

OAuth Flow Details

The OAuth flow works as follows:

1. The server checks for existing tokens in .gcp-saved-tokens.json
2. If no tokens exist or they're expired:
   • The server starts a local web server on port 3000 (or 3001 if 3000 is in use)
   • It generates an authorization URL and opens your browser
   • You log in with your Google account and grant permissions
   • Google redirects back to http://localhost:3000/oauth2callback with an authorization code
   • The server exchanges this code for access and refresh tokens
   • Tokens are saved securely for future use

Security Notes

• OAuth credentials are stored in gcp-oauth.keys.json
• Authentication tokens are stored in .gcp-saved-tokens.json with 600 permissions.
• Tokens refresh automatically before expiration.
• If token refresh fails, you'll be prompted to re-authenticate.
• Never commit OAuth credentials or token files to version control.

Calendar Event Features

The server provides comprehensive event management capabilities:

Creating Events

The create-event tool supports the following parameters:

Parameter	Description	Example
calendarId	ID of the calendar to create event in	"primary" or "user@example.com"
summary	Title of the event	"Team Meeting"
description	Description of the event	"Weekly team sync to discuss progress"
start	Start time (ISO format or object)	"2025-04-01T10:00:00Z" or {"dateTime": "2025-04-01T10:00:00", "timeZone": "America/Los_Angeles"}
end	End time (ISO format or object)	"2025-04-01T11:00:00Z" or {"dateTime": "2025-04-01T11:00:00", "timeZone": "America/Los_Angeles"}
location	Location of the event	"Conference Room B" or "https://meet.google.com/abc-defg-hij"
attendees	List of attendees	[{"email": "colleague@example.com"}]
recurrence	Recurrence rules	["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"]
colorId	Color ID (1-11)	"7" (Peacock blue)
reminders	Reminder settings	{"useDefault": false, "overrides": [{"method": "email", "minutes": 30}, {"method": "popup", "minutes": 10}]}

Color IDs Reference

ID	Color Name	Light Theme	Dark Theme
1	Lavender	#A4BDFC	#7986CB
2	Sage	#7AE7BF	#33B679
3	Grape	#DBADFF	#8E24AA
4	Flamingo	#FF887C	#E67C73
5	Banana	#FBD75B	#F6BF26
6	Tangerine	#FFB878	#F4511E
7	Peacock	#46D6DB	#039BE5
8	Graphite	#E1E1E1	#616161
9	Blueberry	#5484ED	#3F51B5
10	Basil	#51B749	#0B8043
11	Tomato	#DC2127	#D50000

Recurrence Rules

Recurrence rules follow the iCalendar RFC 5545 format. Common patterns:

• Daily: RRULE:FREQ=DAILY
• Weekly on Monday, Wednesday, Friday: RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
• Every two weeks: RRULE:FREQ=WEEKLY;INTERVAL=2
• Monthly on the first Monday: RRULE:FREQ=MONTHLY;BYDAY=1MO
• Until a specific date: RRULE:FREQ=WEEKLY;UNTIL=20251231T235959Z
• For a specific number of occurrences: RRULE:FREQ=WEEKLY;COUNT=10

Updating Events

The update-event tool supports the same parameters as create-event, plus:

Parameter	Description	Example
eventId	ID of the event to update	"abc123def456"

Listing Events

The list-events tool supports:

Parameter	Description	Example
calendarId	ID of the calendar to list events from	"primary"
timeMin	Start time in ISO format (optional)	"2025-04-01T00:00:00Z"
timeMax	End time in ISO format (optional)	"2025-04-30T23:59:59Z"

Usage

The server provides the following tools:

Tool	Description
list-calendars	List all available calendars
list-events	List events from a calendar
create-event	Create a new calendar event
update-event	Update an existing calendar event
delete-event	Delete a calendar event

Using with Claude Desktop

1. Modify your Claude Desktop config file (e.g., /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "google-calendar": {
         "command": "node",
         "args": ["path/to/build/index.js"]
       }
     }
   }
   

   Or with Bun:

   {
     "mcpServers": {
       "google-calendar": {
         "command": "bun",
         "args": ["path/to/build/index.js"]
       }
     }
   }
   

2. Restart Claude Desktop.

Example Use Cases

📅 Add events from screenshots and images

Add this event to my calendar based on the attached screenshot.

✅ Supported formats: PNG, JPEG, GIF
✅ Extracts details like date, time, location, description

🔎 Check attendance

Which events tomorrow have attendees who haven't accepted the invitation?

🤖 Auto-schedule meetings

Here's availability from someone I'm interviewing. Find a time that works on my work calendar.

📆 Find free time across calendars

Show my available time slots for next week. Consider both my personal and work calendar.

📝 Create recurring events

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

🔄 Update multiple events

Move all my meetings on Friday to Thursday at the same times.

Troubleshooting

Issue	Solution
OAuth token expires after 7 days	You must re-authenticate if the app is in testing mode.
OAuth token errors	Ensure gcp-oauth.keys.json is formatted correctly.
TypeScript build errors	Run npm install and npm run build.
Image processing issues	Ensure the image format is PNG, JPEG, or GIF.
Port conflicts	The auth server tries ports 3000 and 3001. Ensure one is available.
"Invalid client" error	Check that your OAuth credentials are correct and the app is properly configured in Google Cloud Console.

Security Notes

• The server runs locally and requires OAuth authentication.
• OAuth credentials must be stored in gcp-oauth.keys.json in the project root.
• Tokens refresh automatically when expired.
• DO NOT commit credentials or tokens to version control.
• For production use, get your OAuth app verified by Google.

Future Improvements

Here are some potential enhancements for future development:

1. Calendar Integration Enhancements

   • Support for working with calendar resources (rooms, equipment)
   • Free/busy time queries across multiple calendars
   • Support for conference solutions (Google Meet, Zoom integration)
   • Working with calendar access control lists (ACLs)

2. User Experience

   • Web-based UI for configuration and monitoring
   • Support for multiple Google accounts
   • Improved error handling and recovery
   • Batch operations for multiple events

3. Advanced Features

   • Natural language processing for event creation
   • Integration with other Google services (Gmail, Tasks, etc.)
   • Calendar analytics and reporting
   • Event templates and quick-create options
   • Conflict detection and resolution

4. Security and Deployment

   • Support for service accounts for server-to-server applications
   • Docker containerization for easier deployment
   • Environment variable configuration
   • Improved token storage with encryption

5. Performance Optimizations

   • Caching frequently accessed calendar data
   • Parallel processing for batch operations
   • Optimized image processing for event extraction

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Want to contribute?

1. Fork the repository.
2. Create a new branch:

   git checkout -b feature-branch
   

3. Make changes & commit:

   git commit -m "Added new feature"
   

4. Push and open a pull request:

   git push origin feature-branch
   

Attribution

This project is a fork of the original nspady/google-calendar-mcp repository.

Stay Updated

🔗 GitHub: pashpashpash/google-calendar-mcp

---

TL;DR Setup

git clone https://github.com/pashpashpash/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build
node build/index.js

Then connect your Google Calendar and you're good to go! 🚀