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

Or clone this repository:

Configuration

Configure the MCP server with your Google OAuth2 credentials:

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

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

List Upcoming Events

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

Building

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