gcal-mcp

An MCP server for Google Calendar and Google Tasks, designed for use with Claude Code. Paste a flight confirmation, manage tasks with energy-aware scheduling, queue articles for reading — all through natural language.

What It Does

• Flight events — Paste a confirmation email, get a timezone-aware calendar event (SFO → JFK | AA 1234)

• Lodging events — Paste a booking confirmation, get 3 events: all-day stay span, timed check-in, timed check-out

• Reading queue — Save articles to read later, batch-schedule them into configurable morning reading slots

• Task manager — Create tasks with Eisenhower priority quadrants and energy levels, synced to Google Tasks

• Energy-aware scheduling — Define your daily energy profile; high-energy tasks get scheduled into your peak hours

• Daily planning — Get optimized schedule proposals, rearrange task blocks, set tickler reminders

Setup

1. Google Cloud Project

1. Go to Google Cloud Console and create a new project

2. Enable the Google Calendar API and Google Tasks API (APIs & Services > Library)

3. Configure the OAuth consent screen:

   • User type: External

   • Add scopes: https://www.googleapis.com/auth/calendar and https://www.googleapis.com/auth/tasks

   • Add your Google email as a test user

   • Publishing status: leave as "Testing"

4. Create OAuth credentials:

   • Credentials > Create Credentials > OAuth client ID

   • Application type: Desktop app

   • Download the JSON file and save it as credentials.json in the project root

2. Install & Build

git clone <this-repo>
cd gcal-mcp
npm install
npm run build

3. Authenticate

Run the one-time OAuth setup (this opens your browser):

npm run auth

You'll be redirected to Google to grant calendar and tasks access. After approving, the token is saved locally in data/token.json.

Note: If you're in Google's "Testing" mode, the refresh token expires after 7 days of inactivity. Just run npm run auth again if that happens.

4. Register with Claude Code

Add to your ~/.claude/.mcp.json (global) or project-level .mcp.json:

{
  "mcpServers": {
    "gcal": {
      "command": "node",
      "args": ["/absolute/path/to/gcal-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code. All tools should now be available.

Tools

Calendar

Reading Queue

Task Manager

Scheduling

Usage

Just tell Claude what you want in natural language:

Flights:

"Here's my flight confirmation: [paste email text]"

Lodging:

"Here's my Airbnb booking: [paste email text]"

Tasks:

"Add a task to review the Q3 report, it's urgent and important, high energy, about 45 minutes"

Scheduling:

"Suggest a schedule for tomorrow" "Schedule my pending tasks for today"

Reading:

"Save this article for later: https://example.com/article" "Schedule my reading queue"

Customization

Config file

Copy config.default.json to config.json to override settings:

cp config.default.json config.json

config.json is gitignored, so your personal settings won't be committed. Available options:

Energy profile

Set your energy profile through the set_energy_profile tool. The default profile is:

Your profile is saved in data/profile.json and persists across sessions.

Templates

Each template file has customizable constants at the top:

After modifying templates, rebuild with npm run build.

Project Structure

├── config.default.json       # Default settings (tracked)
├── config.json               # Your local overrides (gitignored)
├── credentials.json          # OAuth client credentials (gitignored, you provide)
├── data/                     # Runtime data (gitignored)
│   ├── token.json            # OAuth refresh token
│   ├── reading-queue.json    # Reading queue
│   ├── tasks-meta.json       # Task metadata (quadrant, energy, scheduling)
│   └── profile.json          # Energy profile
src/
├── index.ts                  # MCP server entry point, tool registration
├── config.ts                 # Config loader (defaults + local overrides)
├── auth.ts                   # OAuth2 flow + token management
├── auth-cli.ts               # Standalone auth script for first-time setup
├── calendar.ts               # Google Calendar API wrapper
├── reading-queue.ts          # Reading queue persistence
├── tasks.ts                  # Google Tasks API wrapper
├── tasks-meta.ts             # Local task metadata (quadrant, energy, scheduling)
└── templates/
    ├── flight.ts             # Flight event formatting
    ├── lodging.ts            # Lodging event formatting
    ├── reading.ts            # Reading event formatting
    └── task.ts               # Task time block formatting

Google Calendar Event Colors

Available colors: Lavender (1), Sage (2), Grape (3), Flamingo (4), Banana (5), Tangerine (6), Peacock (7), Graphite (8), Blueberry (9), Basil (10), Tomato (11).

License

MIT — see LICENSE.