Weekly Planning Assistant MCP
Provides tools for analyzing Google Calendar data, including week overview, danger zone detection, workout planning, and commute planning.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Weekly Planning Assistant MCP What does my week look like?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Weekly Planning Assistant MCP
An intelligent MCP server that turns your Google Calendar into actionable weekly insights through natural conversation.
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
Related MCP server: Summary MCP
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 --> AThis 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 sync2. Configure Settings
# Copy example configuration
cp config.example.json config.json
# Edit with your preferences
nano config.jsonExample 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
Go to Google Cloud Console
Click "New Project"
Name it (e.g., "Weekly Planner")
Click "Create"
B. Enable Calendar API
Search for "Google Calendar API"
Click "Enable"
C. Configure OAuth Consent Screen
Go to "APIs & Services" → "OAuth consent screen"
Select "External" user type
Fill in app name and your email
Click "Save and Continue" through all steps
Under "Test users", click "+ ADD USERS"
Add your Gmail address
D. Create OAuth Credentials
Go to "Credentials" → "Create Credentials" → "OAuth client ID"
Application type: "Desktop app" ⚠️ (NOT Web application!)
Name: "Weekly Planner Desktop"
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 authYour 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 (runecho $HOME)/absolute/path/to/weekly-planner-mcpwith 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 # DependenciesTools Provided
analyze_week- Comprehensive weekly overview with day-by-day breakdownfind_danger_zones- Identifies scheduling problems and conflictssuggest_workout_slots- Intelligent workout time suggestions with quality scoringcheck_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:00Workout 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 hoursOffice 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 workoutDevelopment
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 authTroubleshooting
"OAuth credentials not found"
Verify:
ls -la ~/.config/google-calendar-mcp/gcp-oauth.keys.jsonEnsure
GOOGLE_OAUTH_CREDENTIALSis set in Claude Desktop config
"No events returned"
Re-authenticate:
npx -y @cocal/google-calendar-mcp authVerify calendar IDs in
config.jsonCheck 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 authWhat 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
Available Tools
4 toolsanalyze_weekA
Get a comprehensive overview of the upcoming week.
Analyzes calendar events to provide day-by-day breakdown with office days,
meeting hours, gaps, and back-to-back meeting blocks.
Args:
start_date: Week start date (YYYY-MM-DD). Defaults to next Monday.
calendar_ids: List of calendar IDs to analyze. Defaults to ["primary"].
Returns:
Complete weekly analysis with per-day breakdowns and summary statistics.
Inputs: start_date, calendar_ids. Returns: Complete weekly analysis.
check_commute_requirementsA
Identify which days require office commute.
Analyzes calendar events to detect office days and provides:
- Which days require office presence
- Earliest time needed at office
- Warnings about early morning commitments
Args:
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
office_indicators: Keywords indicating office presence. Defaults to config.
calendar_ids: List of calendar IDs. Defaults to ["primary"].
Returns:
List of office days with commute information and warnings.
Inputs: end_date (required), start_date (required), calendar_ids, office_indicators. Returns: result
find_danger_zonesA
Identify scheduling problems and conflicts.
Detects:
- Days with no lunch break (meetings 12-2pm)
- Back-to-back meeting stretches longer than 3 hours
- Days with zero free time during work hours
- Overlapping events (conflicts)
Args:
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
calendar_ids: List of calendar IDs. Defaults to ["primary"].
Returns:
List of identified scheduling problems with severity levels.
Inputs: end_date (required), start_date (required), calendar_ids. Returns: result
suggest_workout_slotsA
Find optimal times for booking fitness classes.
Suggests time slots based on:
- Availability (free time in calendar)
- Preferred time of day
- Duration requirements
- Commute patterns (avoids early morning before office days)
Args:
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
preferred_times: Preferred time categories. Defaults to config setting.
min_duration_minutes: Minimum duration needed. Defaults to config setting.
calendar_ids: List of calendar IDs. Defaults to ["primary"].
Returns:
List of suggested workout slots ranked by quality score.
Inputs: end_date (required), start_date (required), calendar_ids, preferred_times, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: weekly overview, problem detection, workout scheduling, and commute detection. Overlap is minimal (check_commute_requirements focuses on office days, while analyze_week includes office days as part of a broader analysis, but descriptions clearly differentiate).
All tool names follow a consistent verb_noun pattern: analyze_week, find_danger_zones, suggest_workout_slots, check_commute_requirements. No deviations in style or casing.
Four tools are well-scoped for a weekly planning assistant, covering analysis, conflict detection, scheduling suggestions, and commute needs. Each tool earns its place without redundancy.
The surface covers key planning tasks: analysis, conflict detection, workout suggestions, and commute checks. However, it lacks tools for modifying the calendar (e.g., creating events) or deeper integration like travel time estimation, which could be minor gaps for a planning assistant.
Related MCP Connectors
Your AI assistant logs your meals and workouts, then plans your week from what you did.
Read and change Google Calendar and Outlook events, find free time and add meeting links.
Schedule and manage Google Calendar events directly from your workspace. Check availability, view…
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables natural language queries to Google Calendar API for checking appointments, availability, and events. Supports flexible time ranges, timezone handling, and both service account and OAuth authentication methods.-
- FlicenseBqualityNot gradedmaintenanceGenerates AI-powered daily and weekly productivity summaries by analyzing your Slack messages, Google Calendar events, and Gmail activity with automated scheduling and smart filtering.6-
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with intelligent access to Google Calendar data, enabling natural language queries about availability, upcoming events, schedule conflicts, and meeting summaries through context-aware calendar integration.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage calendars and tasks through natural language, supporting Google Calendar operations like event creation, availability checking, and smart scheduling. It features schedule analysis, task reminders, and meeting time recommendations to streamline productivity.MIT