MCP HubMCP Hub
shuntaka9576

cal2prompt

by: shuntaka9576

✨ Fetches your schedule (Google Calendar) and outputs it as a single LLM prompt, with an optional MCP server mode.

11created 31/01/2025
Visit
Google
LLM

📌Overview

Purpose: To provide a command-line tool that retrieves schedules from Google Calendar and transforms them into customizable prompts using a template engine.

Overview: cal2prompt is an experimental command-line utility designed to fetch your schedule from Google Calendar and convert it into tailored text snippets or prompts. It features integration with the Google Calendar API and can run as an experimental Model Context Protocol (MCP) server for advanced functionalities.

Key Features:

  • Google Calendar Integration: Utilizes the Google Calendar API v3 to seamlessly fetch your schedule, ensuring reliable access to calendar data.

  • Flexible LLM Prompt Customization with a Template Engine: Employs the Jinja2 template engine for customizable prompt generation, allowing users to format their calendar data as desired.

  • Blazing Fast: High-speed performance powered by the Rust programming ecosystem, ensuring quick data retrieval and processing.

  • Experimental MCP Mode: Provides the ability to run cal2prompt as an MCP server, facilitating interactions with language models in an experimental environment.

cal2prompt

⚠️ This project is still experimental. Features may change without notice. Use with caution! ⚠️

cal2prompt is a command-line tool that fetches your schedule (e.g., from Google Calendar) and converts it into a custom prompt or text snippet via a template engine. It can output directly to your stdout or run as an experimental MCP (Model Context Protocol) server.

cal2prompt uses the Google Calendar API version 3.

Features

  • 🚀 Google Calendar Integration
    Utilizes the Google Calendar API v3 to fetch your schedule.

  • 📄 Flexible LLM Prompt Customization with a Template Engine
    Customize the generated prompts using the Jinja2 template engine.

  • ⚡️ Blazing fast
    High-speed Processing Powered by the Rust Ecosystem.

  • 🔧 Experimental MCP Mode
    Run cal2prompt as a Model Context Protocol server.

Installation

Brew (MacOS)

brew install shuntaka9576/tap/cal2prompt

Cargo (git)

git clone https://github.com/shuntaka9576/cal2prompt
cd cal2prompt
cargo install --path .

Usage

$ cal2prompt --help
✨ Fetches your schedule (e.g., from Google Calendar) and converts it into a single LLM prompt. It can also run as an MCP (Model Context Protocol) server.

Usage: cal2prompt [OPTIONS] [COMMAND]

Commands:
  mcp   Launch cal2prompt as an MCP server (experimental).
  help  Print this message or the help of the given subcommand(s)

Options:
      --since <DATE>  Start date (YYYY-MM-DD). Requires --until.
      --until <DATE>  End date (YYYY-MM-DD). Requires --since.
      --today         Fetch events for today only.
      --this-week     Fetch events for the current week (Mon-Sun).
      --this-month    Fetch events for the current month (1st - end).
      --next-week     Fetch events for the upcoming week (Mon-Sun).
  -h, --help          Print help
  -V, --version       Print version

Initial setup

1. Setup Google OAuth2.0 Client

We use OAuth2 for authenticating with your Google account. After authentication, the generated token is stored in the oauth file located in your platform’s data directory (e.g., ~/.local/share/cal2prompt/oauth on Linux). When you launch cal2prompt for the first time, the authentication process will begin automatically—simply follow the on-screen instructions.

Currently, you must use your own Calendar API token. The Calendar API token is only granted to a limited number of users and requires Google’s approval. Even if the project owner were to provide a Google-approved client, there would inevitably be security risks. Therefore, you need to create and manage your own token.

Please follow the steps in docs/setup-oauth to create your own Google “project” and obtain an OAuth token.

2. Setup configuration

Configuration is written in Lua. Below is an example of the configuration. You can separate public and private information into separate files if you prefer—simply customize it to suit your needs.

Create ~/.config/cal2prompt/secrets.lua and add the following contents. The file name can be any name as long as it matches the require statement in the config.lua mentioned later.

Specify the clientID, clientSecret, and Calendar ID you created earlier. You can find the Calendar ID in the Google Calendar web UI.

local M = {}

M.google = {
  clientID = "***.apps.googleusercontent.com",
  clientSecret = "***",
  calendarIDs = {
    "example@gmail.com"
  },
}

return M

Create ~/.config/cal2prompt/config.lua and add the following contents:

local cal2prompt = require("cal2prompt") -- builtin module
local os = require("os") -- stdlib
local secrets = require("secrets")

return {
  settings = {
    -- see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    TZ = "Asia/Tokyo",
  },
  source = {
    google = {
      oauth2 = {
        clientID = secrets.google.clientID,
        clientSecret = secrets.google.clientSecret,
      },
      calendar = {
        getEvents = {
          calendarIDs = secrets.google.calendarIDs,
        },
      },
    },
  },
  output = {
    template = [[
Here is your schedule summary. Please find the details below:
{% for day in days %}
## Date: {{ day.date }}
--------------------------------------

### All-Day Events:
{% if day.all_day_events|length == 0 %}
  (No all-day events)
{% else %}
  {% for ev in day.all_day_events %}
  - {{ ev.summary }}
    - (All Day)
    - Location: {{ ev.location or "N/A" }}
    - Description: {{ ev.description or "No description." }}
    - Attendees:
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - (No attendees)
      {% endif %}
  {% endfor %}
{% endif %}

### Timed Events:
{% if day.timed_events|length == 0 %}
  (No timed events)
{% else %}
  {% for ev in day.timed_events %}
  - {{ ev.summary }}
    - Start: {{ ev.start }}
    - End:   {{ ev.end }}
    - Location: {{ ev.location or "N/A" }}
    - Description: {{ ev.description or "No description." }}
    - Attendees:
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - (No attendees)
      {% endif %}
  {% endfor %}
{% endif %}
{% endfor %}
]],
  },
}

3. CLI Authentication

cal2prompt executes the OAuth 2.0 flow to obtain authentication credentials. For detailed step-by-step instructions, please refer to docs/setup-cli-auth

Run:

cal2prompt

Integrating Claude Desktop with MCP

Add the following configuration to ~/Library/Application Support/Claude/claude_desktop_config.json:

  • For mcpServers.cal2prompt.command: specify the full path obtained by running which cal2prompt.
  • For mcpServers.cal2prompt.env.HOME: set explicitly if Claude Desktop does not inherit the HOME environment variable.
{
  "mcpServers": {
    "cal2prompt": {
      "command": "/Users/username/.cargo/bin/cal2prompt",
      "args": ["mcp"],
      "env": {
        "HOME": "/Users/username"
      }
    }
  }
}

Configuration

Config Options

Variable NameRequiredDescriptionDefault Value
settings.TZtrueIANA time zone format. (e.g. America/Los_Angeles Asia/Tokyo)UTC
settings.oauthFilePathfalsePath where OAuth2.0 tokens are temporarily stored. Usually no need to change.~/.local/share/cal2prompt/oauth
source.google.oauth2.clientIDtrueYour Google OAuth2 Client ID used for authenticating with the Google Calendar API.(No default; must be specified)
source.google.oauth2.clientSecrettrueYour Google OAuth2 Client Secret used for authenticating with the Google Calendar API.(No default; must be specified)
source.google.oauth2.scopesfalseScopes to grant to Google OAuth 2.0 client. Refer to Google Calendar API auth scopes for details.[https://www.googleapis.com/auth/calendar.events]
source.google.oauth2.redirectURLfalseThe OAuth2 callback URL to which Google will send responses."http://127.0.0.1:9004"
source.google.calendar.getEvents.calendarIDstrueList of one or more Google Calendar IDs from which to fetch events. Found in Google Calendar settings.(No default; must be specified)
output.templatetrueA string that defines how the fetched calendar data should be formatted/output.(No default; must be specified)
experimental.mcp.insertCalendarEvent.calendarIDfalseThe ID of the Google Calendar to which new events will be inserted when using the experimental MCP feature.None

Environment Variables

Variable NameDescriptionDefault Value
CAL2_PROMPT_CONFIG_FILE_PATHPath to a custom Lua configuration file if not using default.~/.config/cal2prompt/config.lua