Google Calendar MCP Server

# Google Calendar MCP Server A Model Context Protocol (MCP) server for interacting with Google Calendar API, built for [Smithery](https://smithery.ai/). ## 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](https://console.cloud.google.com/) 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 ```bash npm install -g @smithery/cli npm create smithery ``` Or clone this repository: ```bash git clone <repository-url> cd google-calendar-mcp npm install ``` ## Configuration Configure the MCP server with your Google OAuth2 credentials: ```json { "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 ```bash 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 ```typescript 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 ```typescript 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 ```bash 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](https://smithery.ai/docs) - **Google Calendar API**: [Google Calendar API Reference](https://developers.google.com/calendar/api/v3/reference) - **Issues**: Submit issues via GitHub ## Related Projects - [Smithery CLI](https://www.npmjs.com/package/@smithery/cli) - [Model Context Protocol](https://github.com/modelcontextprotocol/specification) - [Google APIs Node.js Client](https://github.com/googleapis/google-api-nodejs-client)