calctl

A command-line tool and MCP server for interacting with Google Calendar.

Installation

You will need to have Go installed on your system.

Using go install

Once the repository is public, you can install the calctl command directly:

go install github.com/ghchinoy/calctl@latest

Make sure that your Go bin directory is in your system's PATH. This is typically $HOME/go/bin.

From Source

To build the tool from source, you can clone the repository and build it manually:

git clone https://github.com/ghchinoy/calctl
cd calctl
go build ./...

Configuration

calctl requires Google Cloud credentials to access your calendar data.

1. Create a Google Cloud Project: If you don't have one already, create a project in the Google Cloud Console.
2. Enable the Google Calendar API:

   gcloud services enable calendar-json.googleapis.com
   

3. Create OAuth 2.0 Credentials:
   • Go to the Credentials page in the Cloud Console.
   • Click "Create Credentials" and choose "OAuth client ID".
   • Select "Desktop app" for the application type.
   • After creation, download the JSON file. It will be named something like client_secret_xxxxxxxx.json.
4. Set up the credentials for calctl: You can either use the --secret-file flag with each command:

   ./calctl --secret-file /path/to/your/client_secret.json week
   

   Or, you can set the CALENDAR_SECRETS environment variable:

   export CALENDAR_SECRETS=/path/to/your/client_secret.json
   ./calctl week
   

Usage

CLI Commands

• week [date]: Display events for the current week. Can optionally take a date in YYYY-MM-DD format.

  ./calctl week
  ./calctl week 2025-08-25
  

• week --analyze: Provides an analysis of the week's events, showing overlaps and your response status.

  ./calctl week --analyze
  

• get [event-id]: Get the details of a specific event.

  ./calctl get <event_id_from_week_command>
  

MCP Server

You can also run calctl as an MCP server to expose its functionality as tools.

• To run over standard I/O:

  ./calctl --mcp
  

  By default, logs will be written to stderr. To write logs to a file, use the --logfile flag:

  ./calctl --mcp --logfile calctl.log
  

• To run over HTTP:

  ./calctl --mcp-http :8080
  

The following tools are available:

• get_weekly_calendar(current_date: str): Get the user's calendar events for the week of the given date (YYYY-MM-DD). If the date is omitted, it uses the current week. This tool returns a JSON object containing a list of full event resources, including all details for each event.
• get_event_details(event_id: str): Get the details of a specific event by its ID.