Google Calendar MCP Server

A Model Context Protocol (MCP) server that intelligently integrates with Google Calendar to provide context-aware responses for AI models. This server analyzes user queries, fetches relevant calendar data, and formats it as concise context to enhance AI assistant capabilities.

Overview

The Google Calendar MCP Server acts as a "smart context engine" that:

• Intercepts user queries about calendar information

• Analyzes queries to understand what calendar context is needed

• Fetches relevant data from Google Calendar API

• Assembles data into a formatted "context package"

• Delivers the context to AI models for hyper-relevant responses

Features

Query Analysis Capabilities

• Detects time references (today, tomorrow, next week, specific dates)

• Identifies intent types (availability check, schedule summary, conflict detection)

• Extracts date/time parameters from natural language

Calendar Data Fetching

• Upcoming events (next N events, events on specific date)

• Event details (title, time, attendees, location, description)

• Availability windows

• Conflict detection

• Meeting summaries

Context Formatting

• Concise event summaries

• Availability status

• Conflict alerts

• Time-aware formatting

Data Source

This MCP server connects to the Google Calendar API to fetch calendar events and provide personalized context based on the user's schedule.

Prerequisites

• Python 3.10 or later

• Google Cloud Project with Google Calendar API enabled

• OAuth 2.0 credentials from Google Cloud Console

Installation

1. Clone or download this repository

2. Create a virtual environment (recommended):

   python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set up Google Calendar API credentials:

   a. Go to the Google Cloud Console

   b. Create a new project or select an existing one

   c. Enable the Google Calendar API:

   • Navigate to "APIs & Services" > "Library"

   • Search for "Google Calendar API"

   • Click "Enable"

   d. Configure OAuth consent screen:

   • Go to "APIs & Services" > "OAuth consent screen"

   • Choose "External" (unless you have a Google Workspace account)

   • Fill in the required information

   • Add scopes: https://www.googleapis.com/auth/calendar.readonly

   • Add your email as a test user

   e. Create OAuth 2.0 credentials:

   • Go to "APIs & Services" > "Credentials"

   • Click "Create Credentials" > "OAuth client ID"

   • Choose "Desktop app" as the application type

   • Download the credentials JSON file

   f. Place the credentials file:

   • Rename the downloaded file to credentials.json

   • Place it in the config/ directory

   • The file should be at: config/credentials.json

5. Configure environment variables (optional):

   cp .env.example .env # Edit .env if you need to customize paths

Usage

Running the Server

Start the MCP server:

Or alternatively:

On first run, the server will:

1. Open a browser window for Google OAuth authentication

2. Ask you to sign in and grant calendar access

3. Save the authentication token for future use

MCP Tools

The server provides the following tools:

1. get_calendar_context

Main tool that analyzes a query and returns formatted calendar context.

Example prompts:

• "Am I free tomorrow at 2 PM?"

• "What meetings do I have this week?"

• "Do I have any conflicts next Monday?"

2. check_availability

Check if the user is available at a specific date and time.

Parameters:

• date: Date to check (YYYY-MM-DD format or natural language like "tomorrow")

• time: Time to check (HH:MM format or natural language like "2 PM") - optional

• duration_hours: Duration of the time slot in hours (default: 1.0)

Example:

3. get_upcoming_events

Get upcoming calendar events.

Parameters:

• days: Number of days to look ahead (default: 7)

• max_results: Maximum number of events to return (default: 10)

Example:

4. detect_conflicts

Detect scheduling conflicts for a specific date.

Parameters:

• date: Date to check (YYYY-MM-DD format or natural language like "tomorrow")

Example:

Example Use Cases

Example 1: Availability Check

Query: "Am I free tomorrow at 2 PM?"

Context: "User's calendar for tomorrow shows: 'Team Meeting' from 1:00-2:30 PM. User is NOT free at 2 PM."

AI Response: "No, it looks like you have a 'Team Meeting' scheduled from 1:00 to 2:30 PM tomorrow, so you're not free at 2 PM."

Example 2: Schedule Summary

Query: "What meetings do I have this week?"

Context: "Schedule for the next 7 days: Monday, December 9 - 'Project Review' (10:00 AM - 11:00 AM), 'Client Call' (3:00 PM - 4:00 PM); Tuesday, December 10 - 'Standup' (9:00 AM - 9:30 AM)"

AI Response: "This week you have: Monday - 'Project Review' at 10 AM and 'Client Call' at 3 PM; Tuesday - 'Standup' at 9 AM."

Example 3: Conflict Detection

Query: "Do I have any conflicts next Monday?"

Context: "No conflicts detected for Monday, December 16. You have 2 event(s) scheduled: 'Lunch Meeting' (12:00 PM - 1:00 PM); 'Code Review' (4:00 PM - 5:00 PM)"

AI Response: "No conflicts detected for next Monday. You have 2 events: 'Lunch Meeting' at 12 PM and 'Code Review' at 4 PM."

Project Structure

Error Handling

The server includes comprehensive error handling for:

• API Rate Limiting: Detects and reports rate limit errors with helpful messages

• Authentication Failures: Provides clear guidance on re-authentication

• Network Timeouts: Handles connection issues gracefully

• Invalid Date/Time Parsing: Falls back to defaults when parsing fails

• Missing Credentials: Clear error messages for missing configuration files

Security Notes

• Never commit credentials.json or token.json to version control

• The .gitignore file is configured to exclude sensitive files

• OAuth tokens are stored locally and refreshed automatically

• The server only requests read-only access to your calendar

Troubleshooting

Authentication Issues

• Ensure credentials.json is in the config/ directory

• Delete config/token.json and re-authenticate if you see authentication errors

• Verify that the OAuth consent screen is properly configured

API Errors

• Check that Google Calendar API is enabled in your Google Cloud project

• Verify that you've granted the necessary permissions

• Ensure your Google account has an active calendar

Import Errors

• Make sure all dependencies are installed: pip install -r requirements.txt

• Verify you're using Python 3.10 or later

• Check that you're running from the project root directory

Development

Running Tests

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

License

This project is created for the Build-Your-Own-MCP Challenge.

Acknowledgments

• Built using the Model Context Protocol

• Google Calendar API integration

• MCP Python SDK

Contact

For questions or issues, please open an issue in the repository.