Google Calendar

🚀 Google Calendar MCP Server

A Model Context Protocol (MCP) server built with TypeScript, integrating Google Calendar functionality.

🚀 Quick Start

This is a Model Context Protocol (MCP) server built with TypeScript, seamlessly integrating Google Calendar features. It simplifies the process of interacting with Google Calendar, offering a range of functionalities from authentication to event management.

✨ Features

• Seamless Google Calendar Integration: Supports OAuth 2.0 authentication.
• Persistent Token Storage: Enables automatic authentication.
• Calendar Management: Lists and manipulates calendars and their events.
• Full Lifecycle Event Operations: Creates, reads, updates, and deletes calendar events.
• Event Retrieval by Date Range: Queries calendar events within a specified time frame.
• Real-time Update Push: Supports the Server-Sent Events (SSE) transport protocol.
• Easy Integration: Compatible with Claude and other MCP-compatible AI assistants.

📦 Installation

npm install -g mcp-google-calendar

Or run directly:

npx -y mcp-google-calendar

Prerequisites

1. Node.js (v16 or higher)
2. Google Cloud Platform account
3. Google Calendar API enabled
4. OAuth 2.0 credentials configured

Configuration Guide

1. Google Cloud Platform Configuration

1. Visit Google Cloud Console.
2. Create a new project or select an existing one.
3. Enable the Google Calendar API:
   • Go to "APIs & Services" > "Library".
   • Search for "Google Calendar API".
   • Click "Enable".
4. Configure the OAuth consent screen:
   • Visit "APIs & Services" > "OAuth consent screen".
   • Select the "External" user type (or "Internal" for Google Workspace).
   • Fill in the required information:
     • Application name: mcp-calendar
     • User support email: (your email)
     • Developer contact information: (your email)
   • Add scopes:
     • Click "Add or Remove Scopes".
     • Find and select "https://www.googleapis.com/auth/calendar.events".
     • Add your email as a test user.
   • Complete the setup process.
5. Create OAuth credentials:
   • Go to the "Credentials" section.
   • Click "Create Credentials" > "OAuth Client ID".
   • Select the application type as "Desktop app".
   • Name it (e.g., MCP Calendar Desktop Client).
   • Download the JSON file and save it as credentials.json in the project directory.

2. Environment Configuration

Create a .env file in the project root directory:

# Server configuration
PORT=3420

# Google Calendar API configuration
CREDENTIALS_PATH=./credentials.json

💻 Usage Examples

Starting the Server

Run with standard WebSocket:

npx -y mcp-google-calendar

Run with Server-Sent Events (SSE):

npx -y mcp-google-calendar --sse

Integrating with Claude Desktop

Add the following configuration to claude_desktop_config.json:

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"]
      }
   }
}

Basic Usage

Authentication and Authorization

1. Obtain an authorization code: Get the authorization code required for an access token via OAuth 2.0.
2. Token refresh: Implement an automatic token refresh mechanism to ensure long-term access.

Calendar Management

1. Calendar creation:

const calendar = await createCalendar({
  summary: 'My New Calendar',
  description: 'This is a new calendar created via API'
});

2. Calendar reading: Retrieve detailed information about a specified calendar, including its name and description.
3. Calendar update: Modify the properties of an existing calendar, such as updating its name or description.
4. Calendar deletion: Remove an unwanted calendar.

Event Management

1. Event creation:

const event = await createEvent({
  calendarId: 'primary',
  summary: 'Meeting with Team',
  description: 'Discuss Q4 project plan',
  start: {
    timeZone: 'Asia/Shanghai',
    dateTime: '2023-10-05T09:00:00'
  },
  end: {
    timeZone: 'Asia/Shanghai',
    dateTime: '2023-10-05T10:30:00'
  }
});

2. Event query:

const events = await listEvents({
  calendarId: 'primary',
  timeMin: '2023-10-01T00:00:00',
  timeMax: '2023-10-31T23:59:59'
});

3. Event update:

const updatedEvent = await updateEvent({
  calendarId: 'primary',
  eventId: 'event_id_123',
  summary: 'Updated Meeting'
});

4. Event deletion:

await deleteEvent({
  calendarId: 'primary',
  eventId: 'event_id_123'
});

Real-time Push

Implement real-time event update notifications via SSE, subscribing to all event changes in a specific calendar.

📚 Documentation

Project Structure

src/
├── index.ts          # Entry file
├── calendar.ts       # Calendar management module
├── event.ts          # Event management module
└── auth.ts           # Authentication and authorization module

Getting Started Quickly

1. Install dependencies:

npm install @types/googleapis google-auth-library

2. Initialize the project:

npx tsinit

3. Write code and run:

npm run dev

🔧 Technical Details

Security Precautions

1. Credential management: Ensure the security of the credentials.json file to avoid exposing sensitive information.
2. Permission control: Strictly limit the scope of API call permissions to prevent unauthorized operations.
3. Log monitoring: Monitor API requests and responses in real-time to detect abnormal behavior promptly.
4. Error handling: Design a comprehensive fault-tolerant mechanism for different API error codes and exceptional situations.