Google Calendar MCP Server

A Model Context Protocol (MCP) server for interacting with Google Calendar API, built for Smithery.

Features

• OAuth2 Authentication: Complete OAuth2 flow for secure Google Calendar access

• Calendar Management: List, create, and delete calendars

• Event Operations: Create, read, update, and delete calendar events

• Comprehensive Event Details: Support for attendees, reminders, locations, and more

• All-Day Event Support: Handle both timed and all-day events

• Search Functionality: Search events by text and time ranges

Prerequisites

Before using this MCP server, you need:

1. Node.js 18+ installed

2. Google Cloud Console project with Calendar API enabled

3. OAuth2 credentials (Client ID and Client Secret)

Google Cloud Setup

1. Create a Google Cloud Project

1. Go to 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"

2. Configure OAuth Consent Screen

1. Go to "APIs & Services" > "OAuth consent screen"

2. Choose "External" user type

3. Fill in the required information:

   • App name: "Your App Name"

   • User support email: Your email

   • Developer contact information: Your email

4. Add scopes (optional for testing):

   • https://www.googleapis.com/auth/calendar

   • https://www.googleapis.com/auth/calendar.events

3. Create OAuth2 Credentials

1. Go to "APIs & Services" > "Credentials"

2. Click "Create Credentials" > "OAuth 2.0 Client IDs"

3. Choose "Web application"

4. Add authorized redirect URIs:

   • http://localhost:3000/oauth2callback

5. Download the JSON file and note your Client ID and Client Secret

Installation

Using Smithery CLI

npm install -g @smithery/cli
npm create smithery

Or clone this repository:

git clone <repository-url>
cd google-calendar-mcp
npm install

Configuration

Configure the MCP server with your Google OAuth2 credentials:

{
  "clientId": "your-google-client-id.apps.googleusercontent.com",
  "clientSecret": "your-google-client-secret",
  "redirectUri": "http://localhost:3000/oauth2callback",
  "refreshToken": "optional-refresh-token-for-permanent-access"
}

Configuration Parameters

• clientId (required): Google OAuth2 Client ID from Google Cloud Console

• clientSecret (required): Google OAuth2 Client Secret from Google Cloud Console

• redirectUri (optional): OAuth2 redirect URI (default: http://localhost:3000/oauth2callback)

• refreshToken (optional): Pre-existing refresh token for permanent access

Usage

Development

npx @smithery/cli dev

Authentication Flow

1. Generate OAuth URL:

   Tool: generate_oauth_url

2. Visit the URL and authorize the application

3. Exchange Authorization Code:

   Tool: exchange_auth_code
   Parameters: { "auth_code": "code-from-redirect" }

4. Save the refresh token for future use in your configuration

Available Tools

Authentication Tools

• generate_oauth_url - Generate OAuth2 authorization URL

• exchange_auth_code - Exchange authorization code for tokens

• check_auth_status - Check current authentication status

Calendar Management

• list_calendars - List all accessible calendars

• get_calendar - Get detailed calendar information

• create_calendar - Create a new calendar

• delete_calendar - Delete a calendar (except primary)

Event Management

• list_events - List events with filtering options

• get_event - Get detailed event information

• create_event - Create a new event

• update_event - Update an existing event

• delete_event - Delete an event

Example Usage

Create an Event

Tool: create_event
Parameters: {
  "calendar_id": "primary",
  "summary": "Team Meeting", 
  "description": "Weekly sync meeting",
  "start_time": "2024-01-15T10:00:00Z",
  "end_time": "2024-01-15T11:00:00Z",
  "location": "Conference Room A",
  "attendees": ["colleague@company.com"],
  "timezone": "America/New_York"
}

List Upcoming Events

Tool: list_events
Parameters: {
  "calendar_id": "primary",
  "time_min": "2024-01-15T00:00:00Z",
  "time_max": "2024-01-22T23:59:59Z",
  "max_results": 20
}

Security Best Practices

1. Store credentials securely - Never commit OAuth2 credentials to version control

2. Use refresh tokens - Configure access_type: "offline" to get refresh tokens

3. Limit scopes - Only request necessary Calendar API scopes

4. Monitor usage - Keep track of API usage in Google Cloud Console

Error Handling

The MCP server provides detailed error messages for common issues:

• Authentication errors - Clear guidance on OAuth2 setup

• API quota limits - Information about rate limiting

• Permission errors - Help with scope and access issues

• Invalid parameters - Validation errors with helpful descriptions

Development

Project Structure

google-calendar-mcp/
├── src/
│   ├── index.ts           # Main MCP server entry point
│   └── tools/
│       ├── auth.ts        # Authentication tools
│       ├── calendars.ts   # Calendar management tools
│       └── events.ts      # Event management tools
├── package.json
├── smithery.yaml
└── README.md

Building

npx @smithery/cli build

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Documentation: Smithery Documentation

• Google Calendar API: Google Calendar API Reference

• Issues: Submit issues via GitHub

Related Projects

• Smithery CLI

• Model Context Protocol

• Google APIs Node.js Client