gcallm: Google Calendar w/ Claude

gcallm is a simple CLI that uses Claude to add events to Google Calendar in natural language. It supports text input, screenshots, clipboard. It also supports interactive workflows where you use a text editor to input the gcal information, as well as asking the user for confirmation if it finds significant conflict. I found it useful. I hope you do too!

Quickstart

$ gcallm "Coffee with Sarah tomorrow at 2pm"
✅ Created event:
Coffee with Sarah
- Date & Time: Tomorrow at 2:00 PM - 3:00 PM
- Calendar: primary

• Direct input - gcallm "Meeting tomorrow"
• Screenshots - gcallm -s
• Clipboard - gcallm -c
• Stdin - pbpaste | gcallm
• Editor - gcallm (opens $EDITOR)
• URL - gcallm "https://example.com/event"

Installation

Option 1: Install from PyPI (Recommended)

Using pip:

pip install gcallm

Using uv (faster):

uv tool install gcallm

Option 2: Install from Source

git clone https://github.com/WarrenZhu050413/gcallm.git
cd gcallm
make install

For development:

make dev    # Install in editable mode

Quick Start

1. Get Google OAuth Credentials

1. Go to Google Cloud Console
2. Enable Google Calendar API
3. Create OAuth credentials (Desktop app)
4. Download the JSON file and save it (e.g., ~/gcp-oauth.keys.json)

Detailed instructions: See docs/oauth.md

2. Configure OAuth Credentials

gcallm setup ~/gcp-oauth.keys.json

3. Authenticate

export GOOGLE_OAUTH_CREDENTIALS="$HOME/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth

This opens your browser to grant calendar permissions.

4. Verify Setup

gcallm verify

Expected output:

✓ Google Calendar MCP: Working
✓ Claude Agent SDK: Working
✅ All checks passed!

5. Add Your First Event

gcallm "Test event tomorrow at 3pm"

Usage

# Natural language
gcallm "Coffee with Sarah tomorrow at 2pm"

# From screenshot
gcallm -s                    # Latest screenshot
gcallm --screenshots 3       # Latest 3 screenshots

# From clipboard
gcallm -c

# From stdin
pbpaste | gcallm
cat events.txt | gcallm

# Interactive mode (check conflicts)
gcallm -i "Meeting tomorrow at 2pm"

# Ask questions
gcallm ask "What's on my calendar today?"

# No args = open editor
gcallm

Full documentation: See docs/cli.md

Documentation

• CLI Usage Guide - Complete command reference and usage examples
• OAuth Setup - Detailed OAuth configuration instructions
• CLAUDE.md - Developer documentation for contributing

Key Features Explained

Screenshot Support

Take a screenshot of an event flyer, email, or calendar, then run:

gcallm -s

Claude analyzes the screenshot and creates the event automatically. No manual typing needed!

Interactive Mode

Check for scheduling conflicts before creating events:

gcallm -i "Workshop tomorrow 2-5pm"

Claude checks your calendar and warns you about conflicts, letting you decide whether to proceed.

Prerequisites

• Python 3.10+
• Node.js 16+ (for Google Calendar MCP server)
• Google OAuth credentials (see Quick Start)

Troubleshooting

"Calendar tools not available"

The MCP server isn't authenticated. Run:

export GOOGLE_OAUTH_CREDENTIALS="/path/to/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth

Tokens expired (after 7 days)

If your Google Cloud app is in test mode, tokens expire weekly:

npx @cocal/google-calendar-mcp auth

Full troubleshooting: See docs/oauth.md

Development

make dev       # Install in development mode
make test      # Run tests (145 tests)
make format    # Format code
make lint      # Lint code
make build     # Build for PyPI

Developer documentation: See CLAUDE.md

How It Works

┌─────────────┐
│   gcallm    │  Natural language input
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Claude    │  Parses intent, dates, details
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Google Cal  │  Creates events via MCP
│  MCP Server │
└─────────────┘

• Claude Agent SDK - Natural language understanding
• Google Calendar MCP - Direct API access
• Explicit MCP config - No external config files needed

Contributing

Contributions welcome! This project follows TDD (Test-Driven Development).

1. Fork the repository
2. Create a feature branch
3. Write tests first (Red-Green-Refactor)
4. Ensure all tests pass (make test)
5. Submit a Pull Request

See CLAUDE.md for architecture details.

Acknowledgments

• OAuth Setup: Instructions adapted from @cocal/google-calendar-mcp
• Coding Agent: Uses Claude Code
• Agent Development Environment: Uses orchestra

License

MIT License - see LICENSE file for details

Author

Created by Warren Zhu (@WarrenZhu050413)