⚠️ 本项目仍处于实验阶段。功能可能会在未通知的情况下发生变化。请谨慎使用！⚠️

cal2prompt

cal2prompt 是一个命令行工具，可以从您的日历（例如 Google 日历）获取日程，并通过模板引擎将其转换为自定义提示或文本片段。它可以将结果直接输出到标准输出，或者作为实验性的 MCP（模型上下文协议）服务器运行。

cal2prompt 使用 Google 日历 API 版本 3。

命令行示例

模型上下文协议（MCP）示例（实验性）

功能

• 🚀 Google 日历集成
  使用 Google 日历 API v3 获取您的日程。

• 📄 灵活的 LLM 提示定制，使用模板引擎
  使用 Jinja2 模板引擎自定义生成的提示。

• ⚡️ 闪电般快速
  高速处理，由 Rust 生态系统提供支持。

• 🔧 实验性 MCP 模式
  将 cal2prompt 运行为 模型上下文协议 服务器。

安装

Brew (MacOS)

brew install shuntaka9576/tap/cal2prompt

Cargo (git)

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

使用方法

$ cal2prompt --help
✨ 从您的日历（如 Google 日历）获取日程并将其转换为单个 LLM 提示。它也可以作为 MCP（模型上下文协议）服务器运行。

用法：cal2prompt [选项] [命令]

命令：
  mcp   启动 cal2prompt 作为 MCP 服务器（实验性）。
  help  打印此消息或给定子命令的帮助信息

选项：
      --since <日期>  开始日期（YYYY-MM-DD）。需要与 --until 一起使用。
      --until <日期>  结束日期（YYYY-MM-DD）。需要与 --since 一起使用。
      --today         只获取今天的事件。
      --this-week     获取本周的事件（周一至周日）。
      --this-month    获取本月的事件（1号至月底）。
      --next-week     获取下周的事件（周一至周日）。
  -h, --help          打印帮助信息
  -V, --version       打印版本信息

初始设置

1. 设置 Google OAuth2.0 客户端

我们使用 OAuth2 对您的 Google 账户进行身份验证。认证后，生成的令牌将存储在位于平台数据目录中的 oauth 文件中（例如，在 Linux 上为 ~/.local/share/cal2prompt/oauth）。首次启动 cal2prompt 时，身份验证过程将自动开始——只需按照屏幕上的说明操作即可。

目前，您必须使用自己的日历 API 令牌。日历 API 令牌仅授予有限数量的用户，并且需要 Google 的批准。即使我是项目的拥有者，提供了经过 Google 批准的客户端，也会不可避免地存在安全风险。因此，您需要创建并管理自己的令牌。

请按照 docs/setup-oauth 中的步骤来创建自己的 Google“项目”并获得 OAuth 令牌。

2. 设置配置

配置文件使用 Lua 编写。以下是一个配置示例。如果您愿意，可以将公共信息和私有信息分开存储到不同的文件中——只需根据您的需求进行自定义即可。

创建 ~/.config/cal2prompt/secrets.lua 并添加以下内容。文件名可以是任意名称，只要与稍后提到的 config.lua 中的 require 语句匹配即可。

请指定您之前创建的 clientID、clientSecret 和日历 ID。您可以在 Google 日历 Web UI 中找到日历 ID。

local M = {}

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

return M

创建 ~/.config/cal2prompt/config.lua 并添加以下内容：

local cal2prompt = require("cal2prompt") -- 内置模块
local os = require("os") -- 标准库
local secrets = require("secrets")

return {
  settings = {
    -- 参见 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    -- TZ = "Etc/UTC",
    TZ = "Asia/Tokyo",
    -- TZ = "America/Los_Angeles"
    -- TZ - "Asia/Shanghai"
  },
  source = {
    google = {
      oauth2 = {
        clientID = secrets.google.clientID,
        clientSecret = secrets.google.clientSecret,
      },
      calendar = {
        getEvents = {
          calendarIDs = secrets.google.calendarIDs,
        },
      },
    },
  },
  output = {
    -- template = cal2prompt.template.google.standard
    template = [[
这是您的日程概要，请参阅以下详细信息：
{% for day in days %}
## 日期：{{ day.date }}
--------------------------------------

### 全天事件：
{% if day.all_day_events|length == 0 %}
  （无全天事件）
{% else %}
  {% for ev in day.all_day_events %}
  - {{ ev.summary }}
    - （全天）
    - 地点：{{ ev.location or "N/A" }}
    - 描述：{{ ev.description or "无描述。" }}
    - 参加人：
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - （无参加人）
      {% endif %}
  {% endfor %}
{% endif %}

### 定时事件：
{% if day.timed_events|length ==  0 %}
  （无定时事件）
{% else %}
  {% for ev in day.timed_events %}
  - {{ ev.summary }}
    - 开始时间：{{ ev.start }}
    - 结束时间：{{ ev.end }}
    - 地点：{{ ev.location or "N/A" }}
    - 描述：{{ ev.description or "无描述。" }}
    - 参加人：
      {% if ev.attendees|length > 0 %}
        {% for a in ev.attendees %}
        - {{ a }}
        {% endfor %}
      {% else %}
      - （无参加人）
      {% endif %}
  {% endfor %}
{% endif %}
{% endfor %}
]],
  },
}

3. 命令行身份验证

cal2prompt 执行 OAuth 2.0 流程以获取身份验证凭据。详细的分步流程说明，请参阅 docs/setup-cli-auth

cal2prompt

将 Claude Desktop 与 MCP 集成

请将以下配置添加到 ~/Library/Application\ Support/Claude/claude_desktop_config.json：

• 对于 mcpServers.cal2prompt.command：您必须指定通过运行 which cal2prompt 获得的完整路径。
• 对于 mcpServers.cal2prompt.env.HOME：由于 Claude Desktop 可能不会继承 HOME 环境变量，因此需要显式设置。

{
  "mcpServers": {
    "cal2prompt": {
      "command": "/Users/username/.cargo/bin/cal2prompt",
      "args": ["mcp"],
      "env": {
        "HOME": "/Users/username"
      }
    }
  }
}

配置

配置选项

变量名称	必需	描述	默认值
settings.TZ	true	IANA 时间区格式。（例如 America/Los_Angeles Asia/Tokyo）	UTC
settings.oauthFilePath	false	OAuth2.0 令牌临时存储的路径。通常情况下，用户不需要更改此设置，除非他们有自定义设置。	~/.local/share/cal2prompt/oauth
source.google.oauth2.clientID	true	用于与 Google 日历 API 认证的 Google OAuth2 客户端 ID。	(无默认值；必须指定)
source.google.oauth2.clientSecret	true	用于与 Google 日历 API 认证的 Google OAuth2 客户端密钥。	(无默认值；必须指定)
source.google.oauth2.scopes	false	授予 Google OAuth 2.0 客户端的范围。请参阅 此处 了解范围类型。	[https://www.googleapis.com/auth/calendar.events]
source.google.oauth2.redirectURL	false	Google 将响应发送到的 OAuth2 回调 URL。	"http://127.0.0.1:9004"
source.google.calendar.getEvents.calendarIDs	true	cal2prompt 将从中获取事件的一个或多个 Google 日历 ID 的列表。每个 ID 通常可以在您的 Google 日历设置中找到。如果提供了多个 ID，则会从每个日历中获取事件并将它们按时间顺序合并。	(无默认值；必须指定)
output.template	true	定义如何格式化/输出获取的日历数据的字符串。	(无默认值；必须指定)
experimental.mcp.insertCalendarEvent.calendarID	false	当使用实验性 MCP 功能插入新事件时，Google 日历的 ID。	无

环境

变量名称	描述	默认值
CAL2_PROMPT_CONFIG_FILE_PATH	指向自定义 Lua 配置文件的路径，如果您不想使用默认配置。	~/.config/cal2prompt/config.lua