Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Google Calendar integration capabilities. This server allows AI assistants and applications to interact with Google Calendar through a standardized protocol.

Features

List Events: Retrieve events from Google Calendar with filtering options
Create Events: Create new calendar events with full customization
Update Events: Modify existing calendar events
Delete Events: Remove events from calendars
List Calendars: Get available calendars for the authenticated user
OAuth Authentication: Secure Google Calendar API access

Tools Available

`list_events`

Retrieve events from a Google Calendar with various filtering options.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
timeMin (optional): Lower bound for event start time (RFC3339 timestamp)
timeMax (optional): Upper bound for event start time (RFC3339 timestamp)
maxResults (optional): Maximum number of events (default: 250)
singleEvents (optional): Expand recurring events (default: true)
orderBy (optional): Order events by "startTime" or "updated"

`create_event`

Create a new event in Google Calendar.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
summary (required): Event title
description (optional): Event description
start (required): Start date/time object with dateTime and optional timeZone
end (required): End date/time object with dateTime and optional timeZone
location (optional): Event location
attendees (optional): Array of attendee objects with email and displayName
recurrence (optional): Array of RRULE strings for recurring events

`update_event`

Update an existing calendar event.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
eventId (required): ID of the event to update
summary (optional): New event title
description (optional): New event description
start (optional): New start date/time
end (optional): New end date/time
location (optional): New event location
attendees (optional): New attendees list

`delete_event`

Delete an event from Google Calendar.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
eventId (required): ID of the event to delete

`list_calendars`

List available Google Calendars for the authenticated user.

Parameters:

minAccessRole (optional): Minimum access role filter
showDeleted (optional): Include deleted calendars (default: false)
showHidden (optional): Include hidden calendars (default: false)

Setup

Prerequisites

Google Cloud Project: Create a project in Google Cloud Console
Enable Google Calendar API: Enable the Calendar API for your project
Service Account: Create a service account and download the JSON key file

Installation

Clone this repository
Install dependencies:
```
npm install
```
Copy the environment file and configure:
```
copy .env.example .env
```

Edit .env and set your Google Service Account key file path:

GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json

Building

# Build the TypeScript code
npm run build

# Development mode with hot reload
npm run dev

# Type checking
npm run type-check

# Clean build artifacts
npm run clean

Usage

Running the Server

# Start the compiled server
npm start

# Or run in development mode
npm run dev

Integrating with MCP Clients

Add this server to your MCP client configuration:

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

For VS Code with MCP extension, add to .vscode/mcp.json:

{
  "servers": {
    "google-calendar-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Authentication Setup

Create a Service Account:
- Go to Google Cloud Console
- Navigate to IAM & Admin > Service Accounts
- Create a new service account
- Download the JSON key file
Share Calendar Access:
- Open Google Calendar
- Go to calendar settings
- Share your calendar with the service account email
- Grant "Make changes to events" permission
Configure Environment:
- Place the JSON key file in your project directory
- Update the .env file with the correct path

Development

Project Structure

src/
├── index.ts          # Main MCP server implementation
├── types/            # TypeScript type definitions
└── utils/            # Utility functions

.env.example          # Environment variable template
tsconfig.json         # TypeScript configuration
package.json          # Node.js dependencies and scripts

Adding New Tools

Define a Zod schema for input validation
Create a ToolSchema definition
Implement the async handler function
Register the tool in the server
Add comprehensive error handling

Error Handling

All tools return structured responses:

// Success response
{
  content: [{ type: "text", text: JSON.stringify(result) }]
}

// Error response
{
  content: [{ type: "text", text: JSON.stringify(error) }],
  isError: true
}

Security Considerations

Never commit service account keys to version control
Use environment variables for all sensitive configuration
Implement proper error handling to avoid information leakage
Regularly rotate service account keys
Follow Google Cloud security best practices

Contributing

Fork the repository
Create a feature branch
Make your changes with proper tests
Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Check the Google Calendar API documentation
Review MCP specification
Open an issue in this repository

Google Calendar MCP Server

Features

List Events: Retrieve events from Google Calendar with filtering options
Create Events: Create new calendar events with full customization
Update Events: Modify existing calendar events
Delete Events: Remove events from calendars
List Calendars: Get available calendars for the authenticated user
OAuth Authentication: Secure Google Calendar API access

Tools Available

`list_events`

Retrieve events from a Google Calendar with various filtering options.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
timeMin (optional): Lower bound for event start time (RFC3339 timestamp)
timeMax (optional): Upper bound for event start time (RFC3339 timestamp)
maxResults (optional): Maximum number of events (default: 250)
singleEvents (optional): Expand recurring events (default: true)
orderBy (optional): Order events by "startTime" or "updated"

`create_event`

Create a new event in Google Calendar.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
summary (required): Event title
description (optional): Event description
start (required): Start date/time object with dateTime and optional timeZone
end (required): End date/time object with dateTime and optional timeZone
location (optional): Event location
attendees (optional): Array of attendee objects with email and displayName
recurrence (optional): Array of RRULE strings for recurring events

`update_event`

Update an existing calendar event.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
eventId (required): ID of the event to update
summary (optional): New event title
description (optional): New event description
start (optional): New start date/time
end (optional): New end date/time
location (optional): New event location
attendees (optional): New attendees list

`delete_event`

Delete an event from Google Calendar.

Parameters:

calendarId (optional): Calendar ID (default: "primary")
eventId (required): ID of the event to delete

`list_calendars`

List available Google Calendars for the authenticated user.

Parameters:

minAccessRole (optional): Minimum access role filter
showDeleted (optional): Include deleted calendars (default: false)
showHidden (optional): Include hidden calendars (default: false)

Setup

Prerequisites

Google Cloud Project: Create a project in Google Cloud Console
Enable Google Calendar API: Enable the Calendar API for your project
Service Account: Create a service account and download the JSON key file

Installation

Clone this repository
Install dependencies:
```
npm install
```
Copy the environment file and configure:
```
copy .env.example .env
```

Edit .env and set your Google Service Account key file path:

GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./path/to/your/service-account-key.json

Building

# Build the TypeScript code
npm run build

# Development mode with hot reload
npm run dev

# Type checking
npm run type-check

# Clean build artifacts
npm run clean

Usage

Running the Server

# Start the compiled server
npm start

# Or run in development mode
npm run dev

Integrating with MCP Clients

Add this server to your MCP client configuration:

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

For VS Code with MCP extension, add to .vscode/mcp.json:

{
  "servers": {
    "google-calendar-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Authentication Setup

Create a Service Account:
- Go to Google Cloud Console
- Navigate to IAM & Admin > Service Accounts
- Create a new service account
- Download the JSON key file
Share Calendar Access:
- Open Google Calendar
- Go to calendar settings
- Share your calendar with the service account email
- Grant "Make changes to events" permission
Configure Environment:
- Place the JSON key file in your project directory
- Update the .env file with the correct path

Development

Project Structure

src/
├── index.ts          # Main MCP server implementation
├── types/            # TypeScript type definitions
└── utils/            # Utility functions

.env.example          # Environment variable template
tsconfig.json         # TypeScript configuration
package.json          # Node.js dependencies and scripts

Adding New Tools

Define a Zod schema for input validation
Create a ToolSchema definition
Implement the async handler function
Register the tool in the server
Add comprehensive error handling

Error Handling

All tools return structured responses:

// Success response
{
  content: [{ type: "text", text: JSON.stringify(result) }]
}

// Error response
{
  content: [{ type: "text", text: JSON.stringify(error) }],
  isError: true
}

Security Considerations

Never commit service account keys to version control
Use environment variables for all sensitive configuration
Implement proper error handling to avoid information leakage
Regularly rotate service account keys
Follow Google Cloud security best practices

Contributing

Fork the repository
Create a feature branch
Make your changes with proper tests
Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Check the Google Calendar API documentation
Review MCP specification
Open an issue in this repository