Google Calendar MCP Server Tutorial

A tutorial project demonstrating how to build a Model Context Protocol (MCP) server that integrates with Google Calendar. This server exposes Google Calendar functionality as tools that AI assistants can use.

Note: This is an educational project for learning MCP server development. It is not intended for production use.

Table of Contents

• Overview
• Prerequisites
• Project Structure
• Setup
  • 1. Clone the Repository
  • 2. Install Dependencies
  • 3. Configure Google Cloud
  • 4. Configure Claude Desktop
• Available Tools
• Architecture
• Configuration
• Tech Stack

Overview

This MCP server provides AI assistants with the ability to:

• List and manage calendars
• Create, read, update, and delete calendar events
• Query events with filters (time range, search terms, etc.)

Built with FastMCP for the MCP server implementation and the Google Calendar API for calendar operations.

Prerequisites

• Python 3.12 or higher
• uv package manager
• A Google Cloud project with Calendar API enabled
• OAuth 2.0 credentials (Desktop app type)

Project Structure

google-calendar-mcp-server-tutorial/
├── main.py                 # MCP server entry point
├── config.py               # Configuration management
├── auth.py                 # Google OAuth2 authentication
├── logger.py               # Logging utilities
├── service_factory.py      # Factory for Google API services
├── models/                 # Pydantic request models
│   ├── calendar/           # Calendar metadata models
│   ├── calendars_list/     # Calendar list models
│   └── event/              # Event operation models
├── services/               # Google Calendar API service layer
│   ├── calendar_service.py
│   ├── calendar_list_service.py
│   └── event_service.py
└── tools/                  # MCP tool definitions
    ├── calendar.py
    ├── calendar_list.py
    └── event.py

Setup

1. Clone the Repository

git clone <repository-url>
cd google-calendar-mcp-server-tutorial

2. Install Dependencies

uv sync

3. Configure Google Cloud

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   • Navigate to "APIs & Services" > "Library"
   • Search for "Google Calendar API" and enable it
4. Create OAuth 2.0 credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Select "Desktop app" as the application type
   • Download the JSON file
5. Save the downloaded file as client_secret.json in the project root

4. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "GoogleCalendar": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/google-calendar-mcp-server-tutorial",
        "run",
        "main.py"
      ]
    }
  }
}

Replace /path/to/google-calendar-mcp-server-tutorial with the actual path to your project directory.

On first run, a browser window will open for Google OAuth authentication. After authentication, a token.json file will be created to store your credentials.

Available Tools

The server exposes the following MCP tools:

Calendar Tools

Tool	Description
list_calendars	List all calendars in the user's calendar list
get_calendar	Get metadata for a specific calendar

Event Tools

Tool	Description
list_events	List events from a calendar with optional filters
get_event	Get details of a specific event
create_event	Create a new calendar event
update_event	Update an existing event
delete_event	Delete an event from a calendar

Architecture

The project follows a layered architecture:

MCP Client (Claude Desktop)
        ↓
MCP Server (main.py + FastMCP)
        ↓
Tools (tools/) ←── Models (models/)
        ↓
Services (services/)
        ↓
Google Calendar API

• Tools - Define MCP tools that Claude can call, using Pydantic models for input validation
• Services - Handle business logic and Google Calendar API communication
• Service Factory - Dependency injection for creating and caching service instances

Configuration

Configuration is managed through config.py:

Setting	Default	Description
client_secret_path	./client_secret.json	Path to OAuth client secrets
token_path	./token.json	Path to stored OAuth token
log_file_path	./server.log	Path to log file
log_level	DEBUG	Logging level (configurable via LOG_LEVEL env var)

Tech Stack

• FastMCP - MCP server framework
• Google API Python Client - Google Calendar API integration
• google-auth-oauthlib - OAuth 2.0 authentication
• Pydantic - Data validation and settings management
• uv - Fast Python package manager

License

This project is for educational purposes.