Google Calendar CLI integration for scheduling events with natural language

version
1.0.0
GitHub stars
7

Install

/plugin install gcal-plugin@warren-claude-code-plugin-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace.

Contents

Discovered from source

Commands 2

Google Calendar CLI Usage Guide

Use the gcallm CLI to add events to Google Calendar using natural language.

Quick Reference

Add Events

# Direct text input
gcallm "Meeting with Sarah tomorrow at 3pm"
gcallm "Lunch next Tuesday 12-1pm at Cafe Nero"
gcallm add "Team standup Mon-Fri 9:30am"

# Multiple events at once
gcallm "Team standup Mon-Fri 9:30am, Coffee with Alex Thursday 2pm"

From Files (Preferred for Automation)

# Pipe from file
cat /tmp/gcal/events.txt | gcallm
cat schedule.txt | gcallm

# Echo to stdin
echo "Doctor appointment Friday 10am" | gcallm

From Clipboard

# Uses clipboard if no stdin/args provided
gcallm

From Screenshots

# Parse latest screenshot on Desktop
gcallm -s "Add events from this screenshot"

# Parse multiple screenshots
gcallm --screenshots 2 "Add from last 2 screenshots"

Ask Questions

# General calendar questions
gcallm ask "What's on my calendar today?"
gcallm ask "When is my next meeting?"
gcallm ask "Am I free Thursday afternoon?"

List Calendars

gcallm calendars

Common Workflow

Recommended approach for scripts:

# 1. Write event details to a temp file
cat > /tmp/gcal/events.txt << 'EOF'
Meeting with Prof. Smith Monday 2pm
Coffee with Alex Tuesday 10am
Team standup Wed-Fri 9:30am
EOF

# 2. Pipe to gcallm
cat /tmp/gcal/events.txt | gcallm

Natural Language Examples

gcallm understands flexible date/time formats:

  • "tomorrow at 3pm"
  • "next Tuesday 12-1pm"
  • "Monday through Friday at 9:30am"
  • "December 15th 2pm for 2 hours"
  • "Coffee with Alex 10am at Starbucks"
  • "Team meeting every Monday 9am"

Configuration

# Configure model (default: claude-sonnet-4-20250514)
gcallm config --model claude-sonnet-4-20250514

# Configure custom prompt
gcallm config --prompt "Custom extraction prompt"

# Show current config
gcallm config --show

Config stored at: ~/.config/gcallm/config.json

Verification

# Verify setup
gcallm verify

Troubleshooting

"MCP server not configured" Error

Ensure the Google Calendar MCP is configured in Claude Code:

claude mcp add gcal npx @anthropic/mcp-google-calendar -s local

OAuth Issues

Re-run setup:

gcallm setup ~/path/to/oauth-keys.json

Related Commands

  • /gcal:setup - Set up gcallm with OAuth credentials

Google Calendar CLI Setup

This command guides you through setting up the gcallm CLI for adding events to Google Calendar.

Prerequisites

You need:

  1. OAuth2 credentials from Google Cloud Console
  2. Google Calendar MCP server configured in Claude Code

Step 1: Get OAuth2 Credentials

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google Calendar API:
    • Go to "APIs & Services" > "Enable APIs and Services"
    • Search for "Google Calendar API" and enable it
  4. Create OAuth2 credentials:
    • Go to "Credentials" > "Create Credentials" > "OAuth client ID"
    • Application type: Desktop app
    • Name: "Calendar CLI" (or any name)
    • Click "Create"
  5. Download the credentials JSON file
  6. Save it somewhere accessible (e.g., ~/gcp-oauth.keys.json)

Step 2: Install gcallm

# Install from PyPI
uv tool install gcallm

# Or with pip
pip install gcallm

Verify installation:

which gcallm
# Should output: ~/.local/bin/gcallm (or similar)

Step 3: Configure OAuth Path

Point gcallm to your OAuth credentials:

gcallm setup ~/gcp-oauth.keys.json

Or interactively:

gcallm setup
# Will prompt for path

Step 4: Configure Google Calendar MCP

gcallm requires the Google Calendar MCP server. Add it to Claude Code:

claude mcp add gcal npx @anthropic/mcp-google-calendar -s local

This uses the OAuth credentials you configured.

Step 5: Verify Setup

gcallm verify

Expected output:

Google Calendar MCP: OK
OAuth credentials: Configured

Test with a simple query:

gcallm ask "What's on my calendar today?"

Configuration Files

~/.config/gcallm/
├── config.json         # Settings (model, prompt)
└── oauth_path          # Path to OAuth credentials

# OAuth credentials (shared with other Google tools)
~/gcp-oauth.keys.json   # Or wherever you saved it

Troubleshooting

"MCP server not configured" Error

The Google Calendar MCP server isn't set up:

# Add the MCP server
claude mcp add gcal npx @anthropic/mcp-google-calendar -s local

# Verify it's configured
claude mcp list

"OAuth credentials not found" Error

Re-run setup with the correct path:

gcallm setup /correct/path/to/oauth-keys.json

Authentication Failed

Your OAuth token may have expired. Re-authenticate:

  1. Delete existing credentials: rm ~/.config/gcallm/*
  2. Re-run: gcallm setup ~/gcp-oauth.keys.json
  3. Complete the browser authentication flow

Permission Denied

Ensure the OAuth app has calendar scope:

  1. Go to Google Cloud Console > APIs & Services > OAuth consent screen
  2. Add scope: https://www.googleapis.com/auth/calendar

Related Commands

  • /gcal - Usage guide for gcallm CLI

Sponsors

Details

Marketplace
WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace
Source
gcal-plugin
Category
Community

More from WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace

All 3