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-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add WarrenZhu050413/Warren-Claude-Code-Plugin-Marketplace.
Contents
Discovered from sourceCommands 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:
- OAuth2 credentials from Google Cloud Console
- Google Calendar MCP server configured in Claude Code
Step 1: Get OAuth2 Credentials
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Google Calendar API:
- Go to "APIs & Services" > "Enable APIs and Services"
- Search for "Google Calendar API" and enable it
- Create OAuth2 credentials:
- Go to "Credentials" > "Create Credentials" > "OAuth client ID"
- Application type: Desktop app
- Name: "Calendar CLI" (or any name)
- Click "Create"
- Download the credentials JSON file
- 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:
- Delete existing credentials:
rm ~/.config/gcallm/* - Re-run:
gcallm setup ~/gcp-oauth.keys.json - Complete the browser authentication flow
Permission Denied
Ensure the OAuth app has calendar scope:
- Go to Google Cloud Console > APIs & Services > OAuth consent screen
- 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
