Google Calendar MCP Server

🚀 Google Calendar MCP Server

The Google Calendar MCP Server is a Model Context Protocol (MCP) server that offers comprehensive integration with Google Calendar. It enables AI assistants and applications to interact with Google Calendar via a standardized protocol.

🚀 Quick Start

To get started with the Google Calendar MCP Server, follow the steps below:

Prerequisites

• Create a project in Google Cloud Console.
• Enable the Google Calendar API for your project.
• Create a service account and download the JSON key file.

Installation

1. Clone this repository.
2. Install the dependencies using the following command:

   npm install
   

3. Copy the environment file and configure it:

   copy .env.example .env
   

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

   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

Running the Server

# Start the compiled server
npm start

# Or run in development mode
npm run dev

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

📦 Installation

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.

Steps

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
   

💻 Usage Examples

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.

📚 Documentation

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)

🔧 Technical Details

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
}

📄 License

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

Support

For issues and questions:

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

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes with proper tests.
4. Submit a pull request.

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.