cal-auto-python

Python 自动日历

mcp-name: io.github.danielsousaoliveira/cal-auto-python

一个 MCP 服务，可将你的 GitHub Projects 待办事项连接到 Google Calendar 和 Google Tasks。让你的助手连接它，就可以询问日历上有哪些安排、列出待办事项、利用空闲时间规划一周的工作，或将计划转化为实际事件和待办事项。

左侧的待办事项看板会变成右侧的日程安排，每个 Markdown 复选框都会保留为独立的待办事项：

之前	之后

安装

$ pip install cal-auto-python

这会安装 cal-auto-python 命令，它既可运行 CLI，也可运行 MCP 服务。

一次性授权

服务读取或写入你的日历之前，需要先通过 Google 账号授权一次：

$ cal-auto-python authorize

这会打开浏览器窗口，提示你登录并授予日历和任务访问权限，然后将生成的令牌保存在磁盘上（即下方配置目录中的 token.json）。首次启动服务前请执行此操作；授权过期时也需重新执行，详见故障排除。

授权需要 Google OAuth 客户端：

1. 在 Google Cloud Console 中创建项目（或使用现有项目），并启用 Google Calendar API 和 Google Tasks API。
2. 在 APIs & Services → Credentials 下，创建类型为 Desktop app 的 OAuth 客户端 ID，并下载生成的 JSON 文件。
3. 将其保存为配置目录中的 credentials.json（配置目录位置及修改方法请参阅配置）。

将它连接到你的助手

默认情况下，服务通过 stdio 使用 MCP 通信，这正是这些客户端所需的方式。无论使用哪个客户端，各项功能的行为都相同。

Claude Code

运行一条命令即可注册：

$ claude mcp add auto-calendar \
    -e GITHUB_TOKEN=your_github_token_here \
    -e GITHUB_PROJECT_ID=PVT_xxxxxxxxxx \
    -e CAL_AUTO_TIMEZONE=Europe/Lisbon \
    -- cal-auto-python server

添加 -s user，即可让它在每个项目中都可用，而不只是当前项目。若要避免将令牌写入 ~/.claude.json 或显示在进程列表中，请将设置放入文件并传入该文件。请注意，路径必须是绝对路径，因为 Claude Code 会从你启动它时所在的目录运行服务：

$ claude mcp add auto-calendar -- cal-auto-python server --env-file /absolute/path/to/.env

然后，/mcp 会列出服务及其工具，提示词则会显示为 /auto-calendar:plan-week 和 /auto-calendar:whats-scheduled。使用 claude mcp list 检查注册状态，使用 claude mcp remove auto-calendar 撤销注册。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "auto-calendar": {
      "command": "cal-auto-python",
      "args": ["server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_PROJECT_ID": "PVT_xxxxxxxxxx",
        "CAL_AUTO_TIMEZONE": "Europe/Lisbon"
      }
    }
  }
}

Cursor

添加到项目中的 .cursor/mcp.json（或全局文件 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "auto-calendar": {
      "command": "cal-auto-python",
      "args": ["server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_PROJECT_ID": "PVT_xxxxxxxxxx",
        "CAL_AUTO_TIMEZONE": "Europe/Lisbon"
      }
    }
  }
}

通用（任何支持 stdio 的 MCP 客户端）

{
  "command": "cal-auto-python",
  "args": ["server"],
  "env": {
    "GITHUB_TOKEN": "your_github_token_here",
    "GITHUB_PROJECT_ID": "PVT_xxxxxxxxxx",
    "CAL_AUTO_TIMEZONE": "Europe/Lisbon"
  }
}

无需客户端即可试用该服务：将 MCP Inspector 指向它：

$ npx @modelcontextprotocol/inspector cal-auto-python server

基于 Web 的客户端，或想在一台机器上运行服务、再从另一台机器与其通信的用户，无法启动 stdio 子进程。对他们来说，请改用 HTTP 运行服务：

$ cal-auto-python server --transport http --host 127.0.0.1 --port 8000

HTTP 模式为单用户模式，仅供本地使用。 服务会从磁盘读取一个人的 Google 授权信息，并且没有独立用户的概念；除了 HTTP 端点本身，它不提供任何额外授权机制。在共享或公共网络上公开该服务，会让所有能够访问它的人都能访问这一个日历，因此只能将其绑定到 127.0.0.1 或私有、可信的网络。

前置条件

• 一个 GitHub 个人访问令牌，对你要用于排程的 Projects V2 看板具有读取权限：可以使用具有 read:project 范围的经典令牌（如果看板会追踪私有仓库中的项目，还需添加 repo），也可以使用已授予 Projects 读取权限的细粒度令牌。将其设为 GITHUB_TOKEN。
• 看板的 Projects V2 节点 ID，例如 PVT_xxxxxxxxxx。可通过查询 GitHub GraphQL API 获取项目的 ID，也可根据项目 URL 和 Projects API 文档查找。 将其设为 GITHUB_PROJECT_ID。
• 一个 Google OAuth 客户端（Desktop app 类型），如上文一次性授权所述。

功能

工具	参数	功能说明
status	—	报告已配置的集成，以及是否已完成 Google 授权。不泄露任何密钥。
list_calendar_entries	start、end（YYYY-MM-DD，含起止日期）	列出日期范围内的日历活动和全天事项。
list_todos	—	列出已配置的 Google Tasks 列表中尚未完成的事项。
list_tracker_items	statuses（可选列表，例如 ["Backlog", "In Progress"]）	列出 GitHub Projects 看板中的工作项，可按状态筛选。省略则列出所有项。
plan_week	items、start_date、end_date、working_day_start、working_day_end、timezone（可选）、commitments（可选）	根据给定事项和现有安排，将工作安排到空闲的工作时段。仅执行计算，不会访问任何已配置的账号。
sync_backlog	start_date、end_date、apply（默认值为 false）	获取可安排的待办事项，在现有日历安排中穿插安排，并返回结果。默认仅预览；传入 apply=true 即可创建活动和待办事项。跳过已安排的事项。
create_calendar_entry	summary、start、end、timezone、description（可选）、attendees（可选）	创建一项日历活动。不会安排活动，也不会去重。
create_todo	title、note（可选）、due（可选）	创建一项 Google Task。不会去重。

两个提示词封装了常见工作流，因此在支持它们的客户端中会显示为一键启动项（例如 Claude Code 和 Claude Desktop 中的斜杠命令）。两者均可选填 start_date 和 end_date（YYYY-MM-DD），默认范围为接下来的 7 天。

提示词	功能说明
plan-week	读取待办事项和现有安排，预览日程，并在写入任何内容前等待你的确认。
whats-scheduled	按天汇总日历活动和未完成的待办事项，并标出安排过满的日期以及没有日历时段的待办事项。

CLI 可直接使用相同的日程安排逻辑：

$ cal-auto-python sync --start 2026-08-17 --end 2026-08-21 --apply

sync 默认仅预览；传入 --apply 可创建活动和任务。也可传入 --start/--end（YYYY-MM-DD）或 --working-day-start/--working-day-end（HH:MM），以覆盖默认日期范围（今天加接下来的 2 天）和工作时间。

配置

除 GITHUB_TOKEN、GITHUB_PROJECT_ID 和没有默认值、必须设置的 CAL_AUTO_TIMEZONE 外，以下变量均为可选项。

配置从进程环境中读取。MCP 客户端会在服务器配置的 env 块中传入这些变量。使用 CLI 时，你可以导出这些变量，也可以将 .env.example 复制为 .env，并显式指定命令使用该文件：

$ cal-auto-python sync --env-file .env

--env-file 会加载指定文件（仅在传入该参数时加载——不会自动从工作目录读取任何文件）。只会应用 CAL_AUTO_* 和 GITHUB_* 键；文件中的其他内容都会被忽略，并显示警告。环境中已设置的变量优先于文件中的变量。

变量	默认值	用途
GITHUB_TOKEN	(必填)	用于查询 Projects 看板的 GitHub 令牌。
GITHUB_PROJECT_ID	(必填)	要读取的看板的 GitHub Projects V2 节点 ID。
CAL_AUTO_TIMEZONE	(必填)	用于安排事件的 IANA 时区名称，例如 Europe/Lisbon。
CAL_AUTO_CONFIG_DIR	%APPDATA%\cal-auto-python (Windows)、$XDG_CONFIG_HOME/cal-auto-python 或 ~/.config/cal-auto-python	存放 credentials.json 和 token.json 的目录。
CAL_AUTO_WORKING_DAY_START	09:00	工作日开始时间，格式为 HH:MM。
CAL_AUTO_WORKING_DAY_END	17:00	工作日结束时间，格式为 HH:MM。
CAL_AUTO_CALENDAR_ID	primary	要向其中安排事件的 Google Calendar ID。
CAL_AUTO_TASK_LIST_ID	@default	要在其中创建任务的 Google Tasks 列表 ID。
CAL_AUTO_ATTENDEES	(无)	以逗号分隔的电子邮件地址，将受邀参加已安排的事件。
CAL_AUTO_SCHEDULABLE_STATUSES	Backlog	以逗号分隔的 GitHub Project 状态名称。必须与看板上的状态名称完全一致。
CAL_AUTO_COUNT_ALL_DAY_EVENTS	false	全天事件是否计入空闲/忙碌时段。

故障排除

授权错误 / “Google 账号尚未获授权”
再次运行 cal-auto-python authorize。这也可以修复无法自动刷新的过期授权（Google 会在长期未活动或你在 Google 账号设置中撤销访问权限后撤销刷新令牌）——服务器会明确报告此问题，而不是静默失败。

事件显示的时间不符合预期
检查 CAL_AUTO_TIMEZONE。它必须是有效的 IANA 名称（例如 Europe/Lisbon，不能是 CET 或 UTC 偏移量），并且必须与你实际工作的时区一致——调度器使用此值安排事件，而不是使用系统时区。

看板上明明有卡片，但 list_tracker_items 或 sync_backlog 没有返回任何内容
CAL_AUTO_SCHEDULABLE_STATUSES（默认值为 Backlog）必须与看板的状态列名称完全一致，包括大小写。打开看板并逐字复制状态名称，或者向 list_tracker_items 传入显式的 statuses 参数，以确认看板实际报告的内容。

路线图

[x] 从 github 获取项目数据
[x] 将事件和任务添加到 google calendar
[x] 根据优先级安排
[x] 修复重复的事件和任务
[x] 将硬编码的入口点替换为真正的 CLI
[x] 作为 MCP 服务运行（cal-auto-python server）
[x] 优化事件分配
[x] 在计划变更时更新或移动事件

贡献

想要添加其他任务跟踪器或日历后端？请参阅 docs/ARCHITECTURE.md 了解各层结构和操作说明，并参阅 CONTRIBUTING.md 了解如何运行测试、代码检查工具和类型检查器。

参考资料

Google Calendar API
Github Projects API