cal2prompt

⚠️ 本项目仍处于实验阶段。功能可能会在不通知的情况下更改。请谨慎使用！⚠️

cal2prompt 是一个命令行工具，用于从 Google Calendar 等日历服务中获取日程安排，并通过模板引擎将其转换为自定义提示或文本片段。它可以直接输出到标准输出（stdout），或作为实验性的 MCP（Model Context Protocol）服务器运行。

cal2prompt 使用 Google Calendar API v3 获取日程数据。

CLI 示例 !img

Model Context Protocol (MCP) 示例（实验性） !img

我们使用 OAuth2 进行 Google 账户认证。认证成功后，生成的令牌会存储在平台的用户数据目录中（例如 Linux 下的 ~/.local/share/cal2prompt/oauth）。首次运行 cal2prompt 时，会自动启动认证流程，只需按照屏幕提示操作即可。

目前，您必须使用自己的 Calendar API 令牌。Calendar API 令牌仅授予少数用户，并需要 Google 的批准。即使作为项目所有者提供 Google 批准的客户端，也难免存在安全风险。因此，您需要创建并管理自己的令牌。

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

配置使用 Lua 编写。以下是一个配置示例。您可以将公共信息和私有信息分开存储，只需根据需要进行自定义。

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

请指定您之前创建的 clientID、clientSecret 和 Calendar ID。Calendar ID 可以在 Google Calendar 网页界面中找到。

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

cal2prompt 会执行 OAuth 2.0 流程以获取认证凭据。详细的步骤说明请参考 docs/setup-cli-auth。

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

对于 mcpServers.cal2prompt.env.HOME：由于 Claude Desktop 可能不会继承 HOME 环境变量，因此需要显式设置。

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

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