goldk3y/google-calendar-mcp

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