The cal2prompt tool fetches your schedule from Google Calendar and converts it into customized text that can be used with language models. It offers a command-line interface and can also run as a Model Context Protocol (MCP) server, making it easy to integrate your calendar data with AI assistants.
Install easily with Homebrew:
brew install shuntaka9576/tap/cal2prompt
git clone https://github.com/shuntaka9576/cal2prompt
cd cal2prompt
cargo install --path .
You'll need to create your own Google OAuth credentials to access your calendar:
For detailed OAuth setup instructions, follow the documentation in the original repository.
Create two configuration files:
~/.config/cal2prompt/secrets.lua
local M = {}
M.google = {
clientID = "***.apps.googleusercontent.com",
clientSecret = "***",
calendarIDs = {
"[email protected]"
},
}
return M
~/.config/cal2prompt/config.lua
local cal2prompt = require("cal2prompt")
local os = require("os")
local secrets = require("secrets")
return {
settings = {
TZ = "Asia/Tokyo",
-- Set your timezone as needed
},
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 %}
]],
},
}
Run cal2prompt to trigger the authentication process:
cal2prompt
This will open a browser window where you can authorize the application to access your Google Calendar.
$ cal2prompt --help
Common usage patterns:
# Fetch today's events
cal2prompt --today
# Fetch events for the current week
cal2prompt --this-week
# Fetch events for the current month
cal2prompt --this-month
# Fetch events for next week
cal2prompt --next-week
# Fetch events for a custom date range
cal2prompt --since 2023-05-01 --until 2023-05-07
To use cal2prompt with Claude Desktop, configure it in the Claude Desktop settings:
~/Library/Application\ Support/Claude/claude_desktop_config.json{
"mcpServers": {
"cal2prompt": {
"command": "/Users/username/.cargo/bin/cal2prompt",
"args": ["mcp"],
"env": {
"HOME": "/Users/username"
}
}
}
}
Make sure to replace /Users/username/.cargo/bin/cal2prompt with the full path to your cal2prompt installation (find it using which cal2prompt).
Key configuration settings include:
| Setting | Description |
|---|---|
settings.TZ |
Your timezone in IANA format (e.g., America/Los_Angeles, Asia/Tokyo) |
source.google.oauth2.clientID |
Your Google OAuth2 Client ID |
source.google.oauth2.clientSecret |
Your Google OAuth2 Client Secret |
source.google.calendar.getEvents.calendarIDs |
List of Google Calendar IDs to fetch |
output.template |
Template for formatting calendar data (uses Jinja2 syntax) |
You can customize the environment with:
export CAL2_PROMPT_CONFIG_FILE_PATH=/path/to/custom/config.lua
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "cal2prompt" '{"command":"cal2prompt","args":["mcp"],"env":{"HOME":"${HOME}"}}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"cal2prompt": {
"command": "cal2prompt",
"args": [
"mcp"
],
"env": {
"HOME": "${HOME}"
}
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"cal2prompt": {
"command": "cal2prompt",
"args": [
"mcp"
],
"env": {
"HOME": "${HOME}"
}
}
}
}3. Restart Claude Desktop for the changes to take effect