# 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](#overview)
- [Prerequisites](#prerequisites)
- [Project Structure](#project-structure)
- [Setup](#setup)
  - [1. Clone the Repository](#1-clone-the-repository)
  - [2. Install Dependencies](#2-install-dependencies)
  - [3. Configure Google Cloud](#3-configure-google-cloud)
  - [4. Configure Claude Desktop](#4-configure-claude-desktop)
- [Available Tools](#available-tools)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Tech Stack](#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](https://github.com/jlowin/fastmcp) for the MCP server implementation and the Google Calendar API for calendar operations.

## Prerequisites

- Python 3.12 or higher
- [uv](https://github.com/astral-sh/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

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

### 2. Install Dependencies

```bash
uv sync
```

### 3. Configure Google Cloud

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
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`

```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](https://github.com/jlowin/fastmcp)** - MCP server framework
- **[Google API Python Client](https://github.com/googleapis/google-api-python-client)** - Google Calendar API integration
- **[google-auth-oauthlib](https://github.com/googleapis/google-auth-library-python-oauthlib)** - OAuth 2.0 authentication
- **[Pydantic](https://docs.pydantic.dev/)** - Data validation and settings management
- **[uv](https://github.com/astral-sh/uv)** - Fast Python package manager

## License

This project is for educational purposes.