Weekly Planning Assistant

An intelligent MCP server that turns your Google Calendar into actionable weekly insights through natural conversation.

MCP Python License

What It Does

Ask Claude natural questions about your schedule and get intelligent analysis:

• "What does my week look like?" → Day-by-day breakdown with meeting hours, office days, and free time
• "When should I book boxing classes?" → Ranked workout time suggestions based on your actual schedule
• "Which days am I going to the office?" → Office day detection with commute warnings
• "Do I have any scheduling problems?" → Identifies conflicts, missing lunch breaks, and marathon meeting blocks

How It Works

graph LR
    A[You ask Claude] --> B[Weekly Planner MCP]
    B --> C[Google Calendar MCP]
    C --> D[Your Google Calendar]
    D --> C
    C --> B
    B --> A

This server demonstrates MCP chaining - it acts as both a server (to Claude) and a client (to Google Calendar MCP), providing domain-specific intelligence on top of raw calendar data.

Features

🗓️ Week Analysis

• Office vs. WFH day detection
• Total meeting hours per day
• Free time gaps (>1 hour)
• Back-to-back meeting blocks
• Busiest/lightest day identification

⚠️ Danger Zone Detection

• Missing lunch breaks (meetings 12-2pm)
• Marathon meetings (3+ hours straight)
• Days with zero free time
• Calendar conflicts and overlaps

🏃 Workout Planning

• Quality-scored time slot suggestions
• Preference-based filtering (morning/lunch/evening)
• Commute-aware recommendations
• Duration-based slot matching

🚗 Commute Planning

• Office day detection via keywords
• Earliest arrival time calculation
• Early morning gym warnings
• Multi-calendar support

Installation

Prerequisites

• Python 3.11+ - Download
• Node.js - Download (for Google Calendar MCP)
• Claude Desktop - Download
• Google Account with Calendar access

1. Clone and Install

# Clone the repository
git clone https://github.com/yourusername/weekly-planner-mcp.git
cd weekly-planner-mcp

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Install dependencies
uv sync

2. Configure Settings

# Copy example configuration
cp config.example.json config.json

# Edit with your preferences
nano config.json

Example config.json:

{
  "calendar_ids": ["primary"],
  "office_keywords": ["office", "HQ"],
  "work_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "preferred_workout_times": ["morning", "lunch"],
  "min_workout_duration": 60
}

3. Set Up Google Calendar OAuth

A. Create Google Cloud Project

1. Go to Google Cloud Console
2. Click "New Project"
3. Name it (e.g., "Weekly Planner")
4. Click "Create"

B. Enable Calendar API

1. Search for "Google Calendar API"
2. Click "Enable"

C. Configure OAuth Consent Screen

1. Go to "APIs & Services" → "OAuth consent screen"
2. Select "External" user type
3. Fill in app name and your email
4. Click "Save and Continue" through all steps
5. Under "Test users", click "+ ADD USERS"
6. Add your Gmail address

D. Create OAuth Credentials

1. Go to "Credentials" → "Create Credentials" → "OAuth client ID"
2. Application type: "Desktop app" ⚠️ (NOT Web application!)
3. Name: "Weekly Planner Desktop"
4. Click "Create" and "Download JSON"

E. Save and Authenticate

# Save credentials
mkdir -p ~/.config/google-calendar-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-calendar-mcp/gcp-oauth.keys.json

# Authenticate
export GOOGLE_OAUTH_CREDENTIALS="$HOME/.config/google-calendar-mcp/gcp-oauth.keys.json"
npx -y @cocal/google-calendar-mcp auth

Your browser will open - sign in and grant calendar permissions.

4. Add to Claude Desktop

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

{
  "mcpServers": {
    "weekly-planner": {
      "command": "/Users/yourusername/.local/bin/uv",
      "args": [
        "--directory",
        "/absolute/path/to/weekly-planner-mcp",
        "run",
        "python",
        "-m",
        "weekly_planner",
        "--stdio"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/Users/yourusername/.config/google-calendar-mcp/gcp-oauth.keys.json"
      }
    }
  }
}

Replace:

• /Users/yourusername/ with your actual home directory (run echo $HOME)
• /absolute/path/to/weekly-planner-mcp with full path to this project

5. Restart Claude Desktop

Quit Claude Desktop (⌘+Q) and reopen. Test with:

"What does my week look like?"

Configuration

Basic Settings

Edit config.json to customize behavior:

{
  "calendar_ids": ["primary"],           // Which calendars to analyze
  "office_keywords": ["office", "HQ"],   // Keywords for office detection
  "work_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "preferred_workout_times": ["morning", "lunch", "evening"],
  "min_workout_duration": 60             // Minutes
}

Adding Multiple Calendars

To include work calendars or imported calendars, first list your available calendars, then add their IDs to config.json.

See the full command in the Development section below for listing calendars.

Architecture

Project Structure

weekly-planner-mcp/
├── src/weekly_planner/
│   ├── server.py          # FastMCP server with 4 tools
│   ├── gcal_client.py     # Google Calendar MCP client
│   ├── analysis.py        # Core scheduling analysis logic
│   ├── models.py          # Pydantic models for structured output
│   └── config.py          # Configuration management
├── config.json            # Your configuration
├── config.example.json    # Example configuration
└── pyproject.toml         # Dependencies

Tools Provided

1. analyze_week - Comprehensive weekly overview with day-by-day breakdown
2. find_danger_zones - Identifies scheduling problems and conflicts
3. suggest_workout_slots - Intelligent workout time suggestions with quality scoring
4. check_commute_requirements - Office day detection with commute planning

All tools return structured Pydantic models for type-safe, validated responses.

Example Usage

Week Overview:

You: What does my week look like?

Claude: Here's your week breakdown:

Monday (4.5h meetings)
• Office day detected
• Free slots: 9:00-10:00, 14:00-16:00
• 3-hour back-to-back block in morning

Tuesday (2h meetings)
• Lightest day this week
• Large gap: 11:00-17:00

Workout Planning:

You: When should I book a 60-minute workout this week?

Claude: Best times ranked by quality:

1. Tuesday 11:00-12:00 (Score: 8.5/10)
   • Long gap available
   • Lunch time slot
   • Not near office days

2. Friday 18:30-19:30 (Score: 7.8/10)
   • Evening slot
   • After work hours

Office Days:

You: Which days am I going to the office?

Claude: You have 2 office days this week:

• Monday: Office all day (earliest: 9:30am)
  ⚠️ Early start - avoid morning gym

• Thursday: Afternoon in office (earliest: 2:00pm)
  ✓ Morning free for workout

Development

List Available Calendars

cd /path/to/weekly-planner-mcp
export GOOGLE_OAUTH_CREDENTIALS="$HOME/.config/google-calendar-mcp/gcp-oauth.keys.json"

uv run python -c "
import asyncio, os
os.environ['GOOGLE_OAUTH_CREDENTIALS'] = os.path.expanduser('~/.config/google-calendar-mcp/gcp-oauth.keys.json')
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def list_cals():
    params = StdioServerParameters('npx', ['-y', '@cocal/google-calendar-mcp', 'start'], env=os.environ.copy())
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            result = await s.call_tool('list-calendars', {})
            import json
            for cal in json.loads(result.content[0].text)['calendars']:
                print(f'{cal[\"summary\"]}: {cal[\"id\"]}')
asyncio.run(list_cals())
"

Add calendar IDs to config.json under calendar_ids.

Check Logs

# Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp-server-weekly-planner.log

# Re-authenticate if needed
npx -y @cocal/google-calendar-mcp auth

Troubleshooting

"OAuth credentials not found"

• Verify: ls -la ~/.config/google-calendar-mcp/gcp-oauth.keys.json
• Ensure GOOGLE_OAUTH_CREDENTIALS is set in Claude Desktop config

"No events returned"

• Re-authenticate: npx -y @cocal/google-calendar-mcp auth
• Verify calendar IDs in config.json
• Check logs: tail -f ~/Library/Logs/Claude/mcp-server-weekly-planner.log

"Access denied" during OAuth

• Add yourself as a test user in Google Cloud Console
• Use the exact Gmail address you added
• Application type must be "Desktop app" not "Web application"

"Token expired"

export GOOGLE_OAUTH_CREDENTIALS="$HOME/.config/google-calendar-mcp/gcp-oauth.keys.json"
npx -y @cocal/google-calendar-mcp auth

What This Demonstrates

This project showcases key MCP concepts:

• MCP Chaining - One MCP server calling another MCP server
• Structured Output - Type-safe responses using Pydantic models
• Domain Abstractions - High-level analysis tools built on generic calendar API
• Configuration Management - File-based and environment variable configuration
• FastMCP Usage - Modern MCP server implementation with decorators
• OAuth Integration - Secure Google Calendar API authentication