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

Event Tools

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:

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.