moodjx/mcp-gcalendar

MCP Calendar Server

A Model Context Protocol (MCP) server providing Google Calendar integration for AI assistants. Built with clean architecture principles and comprehensive type safety.

Features

• Event Management: Create, update, delete, and retrieve calendar events
• Availability Checking: Find free time slots and detect scheduling conflicts
• Event Search: Search events by text across titles and descriptions
• Recurring Events: Create and manage repeating events with flexible patterns
• Secure Authentication: Per-request OAuth2 tokens (no server-side credentials storage)

Technologies & Patterns

Core Technologies:

• FastMCP - Modern MCP server framework with decorator-based tools
• Pydantic v2 - Data validation and settings management
• Google Calendar API - Calendar integration via official Python client

Design Patterns:

• Repository Pattern - Data access abstraction layer
• Service Layer Pattern - Business logic separation
• Dependency Injection - Loose coupling via Protocol-based interfaces
• Middleware Pattern - Request/response processing pipeline
• Type-Safe Schemas - Pydantic models for all I/O operations

Quick Start

Prerequisites

• Python 3.13+
• uv package manager
• Google Cloud project with Calendar API enabled
• OAuth2 credentials from Google Cloud Console

Installation

# Clone and install
git clone <repository-url>
cd mcp_calendar
uv sync

# Configure OAuth credentials
cp .env.example .env
# Edit .env with your OAuth client ID and secret

Running

# Start server
uv run python -m src.main

# With debug logging
MCP_CALENDAR_DEBUG=true uv run python -m src.main

Authentication

The server uses per-request OAuth2 authentication:

• Clients provide access tokens with each tool call
• No server-side credential storage or token refresh
• Tokens are excluded from LLM context for security

Configure server OAuth client credentials via environment variables:

MCP_CALENDAR_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
MCP_CALENDAR_OAUTH_CLIENT_SECRET=your-client-secret

Available Tools

• create_event - Create new calendar events
• create_event_allday - Create all-day events
• update_event - Modify existing events
• delete_event - Remove events
• get_event_details - Retrieve event information
• check_availability - Find free time slots
• search_events - Search events by text
• get_events_range - Get events in date range
• create_recurring_event - Create repeating events
• update_recurrence - Modify recurrence patterns
• list_calendars - List available calendars

MCP Client Integration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "calendar": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.main"],
      "cwd": "/path/to/mcp_calendar",
      "env": {
        "MCP_CALENDAR_OAUTH_CLIENT_ID": "your-client-id",
        "MCP_CALENDAR_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Other MCP Clients

The server communicates via stdio following the MCP protocol. Run as a subprocess and communicate via stdin/stdout.

Project Structure

src/
├── main.py                 # Entry point
├── core/                   # Core business logic & MCP server
├── services/              # Service layer (auth, calendar)
├── repositories/          # Data access layer
├── models/               # Pydantic data models
├── interfaces/           # Protocol-based abstractions
└── config/              # Configuration & logging

License

MIT License - see LICENSE file for details.