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

Related MCP server: Google Calendar MCP Server

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

1. Google Cloud Project: Create a project in Google Cloud Console

2. Enable Google Calendar API: Enable the Calendar API for your project

3. Service Account: Create a service account and download the JSON key file

Installation

1. Clone this repository

2. Install dependencies:

   npm install

3. Copy the environment file and configure:

   copy .env.example .env

4. 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

1. 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

2. Share Calendar Access:

   • Open Google Calendar

   • Go to calendar settings

   • Share your calendar with the service account email

   • Grant "Make changes to events" permission

3. 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

1. Define a Zod schema for input validation

2. Create a ToolSchema definition

3. Implement the async handler function

4. Register the tool in the server

5. 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

1. Fork the repository

2. Create a feature branch

3. Make your changes with proper tests

4. 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