schedule-mcp

Personal schedule management MCP server. Connects Google Calendar, Notion Appointments, and Notion Tasks so Claude can help you plan your week, detect conflicts, schedule task work blocks, and keep your calendar and Notion in sync.

Architecture

Google Calendar  ←→  Claude (sync layer)  ←→  Notion Appointments
                                ↓
                         Notion Tasks
                    (linked via GCal event description)

Key design decisions:

• Google Calendar is the source of truth for time
• Notion Appointments is the source of truth for context (type, notes, rich metadata)
• Notion Tasks are linked to calendar events via Notion URLs in the event description (no bidirectional sync needed)
• A GCal Event ID field on each Notion Appointment prevents duplicate sync
• A GCal Series ID field for linking Notion Appointments with recurring GCal events

Tools

Tool	Source	What it does
gcal_list_calendars	GCal	List all your calendars
gcal_get_events	GCal	Fetch events in a date range
gcal_create_event	GCal	Create a calendar event
gcal_update_event	GCal	Update an existing event
gcal_delete_event	GCal	Delete an event
gcal_find_free_slots	GCal	Find available time blocks
notion_get_appointments	Notion	Query appointments with filters
notion_create_appointment	Notion	Add an appointment to Notion
notion_update_appointment	Notion	Update an appointment
notion_get_appointment_by_gcal_id	Notion	Check if a GCal event is already in Notion
notion_get_tasks	Notion	Query tasks with filters
notion_get_overdue_tasks	Notion	Get all overdue tasks
notion_create_task	Notion	Add a new task
notion_update_task	Notion	Update a task
schedule_week_overview	All	Unified week view: events, appointments, tasks due, overdue tasks
schedule_task_block	GCal + Notion	Schedule a work block for a task
schedule_find_conflicts	GCal	Detect overlaps and tight transitions

Notion Database Schema

Appointments database — expected fields:

Field	Type	Notes
Appointment	Title	Appointment name
Start	Date	Start datetime
End	Date	End datetime
Type	Select	Medical, Personal, Work, Other
Status	Status	Scheduled, In progress, Completed
Canceled	Select	Canceled, Not canceled
Recurring	Select	One-Time, Limited Recurring, Recurring
Notes	Rich text	Free-form notes
GCal Event ID	Rich text	Linked GCal event ID (prevents duplicate sync)
GCal Series ID	Rich text	Linked GCal series ID (for recurring events)

Tasks database — expected fields:

Field	Type	Notes
Task name	Title	Task name
Task Status	Select	Not started, In progress, Done, Archived, Overdue
Due	Date	Due date

Setup

1. Prerequisites

• Python 3.11+
• uv (recommended) or pip
• A Google Cloud project with the Calendar API enabled
• A Notion integration with access to your Appointments and Tasks databases

2. Google Calendar API

1. Go to Google Cloud Console
2. Create a project (or use an existing one)
3. Enable the Google Calendar API
4. Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
5. Application type: Desktop app
6. Download the JSON file → save as ~/.schedule_mcp/google_credentials.json (Windows: %USERPROFILE%\.schedule_mcp\google_credentials.json)

3. Notion Integration

1. Go to https://www.notion.so/my-integrations
2. Create a new integration (Internal, Read + Write content)
3. Copy the Internal Integration Token
4. In Notion, open your Appointments database → ... menu → Connections → add your integration
5. Do the same for your Tasks database

4. Configure Environment

# Linux/macOS
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

Then edit .env with your credentials.

5. Install and Run

# Using uv (recommended)
uv sync
uv run schedule-mcp

# Or with pip
pip install -e .
schedule-mcp

The first run will open a browser window for Google OAuth consent. After that, the token is saved and auto-refreshed.

6. Add to Claude MCP Config

Add this to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), merged into the top-level JSON object alongside any existing keys:

{
  "mcpServers": {
    "schedule": {
      "command": "uv",
      "args": ["run", "--project", "C:/Users/YOU/source/repos/schedule_mcp", "schedule-mcp"],
      "env": {
        "GOOGLE_TOKEN_FILE": "C:/Users/YOU/.schedule_mcp/google_token.json",
        "GOOGLE_CREDENTIALS_FILE": "C:/Users/YOU/.schedule_mcp/google_credentials.json",
        "NOTION_TOKEN": "your_token_here",
        "NOTION_APPOINTMENTS_DB_ID": "your_notion_appointments_db_id_here",
        "NOTION_TASKS_DB_ID": "your_notion_tasks_db_id_here",
        "LOCAL_TIMEZONE": "America/Los_Angeles"
      }
    }
  }
}

Replace YOU with your Windows username. On macOS, use ~ paths instead.

Example Claude Prompts

What does my week look like?

Do I have any conflicts or back-to-backs this week?

Find me 90 minutes of free time tomorrow morning for SeattleCouncilmatic work.

Schedule 2 hours for "Add transit data support to SeattleCouncilmatic" 
on Thursday afternoon.

I have a dentist appointment Tuesday at 2pm — add it to both my calendar and Notion.

Show me all my medical appointments this month.

What tasks do I have due this week?

Development

# Verify syntax
python -m py_compile schedule_mcp/server.py

# Run with MCP Inspector for interactive testing
npx @modelcontextprotocol/inspector uv run schedule-mcp

Project Structure

schedule_mcp/
├── pyproject.toml
├── uv.lock
├── .env.example
├── README.md
└── schedule_mcp/
    ├── __init__.py
    ├── server.py              # MCP server entry point
    ├── auth/
    │   ├── __init__.py
    │   └── google_auth.py     # Google OAuth2 flow
    ├── clients/
    │   ├── __init__.py
    │   ├── gcal.py            # Google Calendar API client
    │   └── notion.py          # Notion API client
    └── tools/
        ├── __init__.py        # Exports register_* functions
        ├── calendar.py        # gcal_* MCP tools
        ├── appointments.py    # notion_*appointment* MCP tools
        ├── tasks.py           # notion_*task* MCP tools
        └── schedule.py        # schedule_* cross-source tools