ridafkih/keeper.sh · 上手攻略

  • 仓库：ridafkih/keeper.sh
  • 链接：https://github.com/ridafkih/keeper.sh
  • 分类：skill（个人效率 / 通用 MCP server）
  • 作者：spark
  • 更新：2026-08-22

一、是什么

keeper.sh 是由独立开发者 Rida F'kih 维护的开源日历同步 + 通用 MCP 服务器。它用 TypeScript + Bun 编写、AGPL-3.0 协议发布，可以从 Google Calendar、Outlook、Office 365、iCloud、Fastmail、CalDAV 服务器以及远程托管的 iCal/ICS 链接中拉取事件，再把它们推送到一个或多个目标日历，让所有日历在"忙闲"时间上对齐——核心目的是解决"多个日历时间冲突"问题。

除了同步，它还内建了：

  • 一个 REST API（/api/v1，用 API token 认证）
  • 一个 Model Context Protocol (MCP) 服务器——让 Claude / ChatGPT 这类 AI Agent 能直接读和写你所有的日历
  • 一个 combined iCal feed——可以从任何日历 app 订阅

⚠️ 仓库卡显示 Stars 1245；根据 2026-07 的第三方评测（kalender-sync.de），实际 GitHub stars 约 1,200；该评测提到 v2.13.5 在 2026-07 发布。这两个数字差异说明仓库仍在快速增长，具体当前 stars 以 GitHub 实时显示为准。

二、解决什么问题

日历同步工具并不新鲜（Google 自身支持导入 ICS；Outlook 也有互联功能），但 keeper.sh 解决了三个老问题：

  1. 删除不彻底：在源日历上删了一个事件，目标日历上残留一份。keeper.sh 通过"mapping row"——一个独立的映射记录，其生命周期比事件本身还长——来追踪这个事件，确保下一次同步把目标端的副本也清掉。
  2. 不开源 + 黑盒：主流商业日历同步 SaaS（SyncGene / CalendarBridge 等）闭源，你不知道它怎么处理你的数据。keeper.sh 是 AGPL-3.0，可审计、可自托管。
  3. AI Agent 没法动你的日历：之前 MCP 标准没出，Agent 调度"哪天我有空"得写一堆 Google Calendar OAuth 代码。keeper.sh 自带 MCP server，任何 MCP 兼容客户端（Claude Desktop / Cherry Studio / 自定义 Agent）都能直接调用 list_calendars、query_events、create_event 等工具。

附加价值：跨平台增量同步——Google 用 sync token、Outlook 用 delta link，只拉增量；CalDAV / iCloud / Fastmail 全量 diff；iCal/ICS 全量 diff。这意味着"几千个事件的企业日历"也能 1 分钟级同步完成。

三、快速安装

方式 A：云托管版（推荐非技术用户）

直接去 https://www.keeper.sh/register 注册。免费层（Free）有：

  • 月费 $0
  • Linked Account 上限 2
  • Sync Mapping 上限 3
  • 刷新间隔 30 分钟
  • API 请求 25/天
  • 不含 Event Filters / iCal Feed 自定义

Pro 云托管版（$5/月或 $45/年）解锁：刷新间隔 1 分钟、无限账号/映射、Event Filters、自定义 iCal、无限 API。

方式 B：自托管（推荐有服务器 / 重视数据主权的人）

自托管版本身就是 Pro 等价——所有付费功能开放，但需要自己维护。

最简路径（Docker）：

# 1. 准备环境变量文件
cat > .env <<'EOF'
DATABASE_URL=postgres://keeper:keeper@postgres:5432/keeper
REDIS_URL=redis://redis:6379
BETTER_AUTH_URL=https://keeper.example.com
BETTER_AUTH_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -base64 32)
GOOGLE_CLIENT_ID=...        # 可选，需要自注册 Google OAuth app
GOOGLE_CLIENT_SECRET=...
MICROSOFT_CLIENT_ID=...     # 可选，需要自注册 Microsoft OAuth app
MICROSOFT_CLIENT_SECRET=...
WEBHOOK_PUBLIC_URL=...      # 可选，开启 Realtime Push（Pro）需要
EOF

# 2. 拉镜像并起服务（仓库 docker-compose.yml 已经配好）
docker compose up -d

# 3. 打开 https://keeper.example.com（推荐用 Caddy 反代 + 自动 TLS）

推荐从 keeper-standalone 镜像起步（包含 web + api + cron + worker + mcp + Postgres + Redis），路径上"最少会出错"。

方式 C：本地开发模式（适合贡献代码或测试）

前置：Bun v1.3.11+、Docker、Docker Compose。

# 1. 克隆
git clone https://github.com/ridafkih/keeper.sh.git
cd keeper.sh

# 2. 安装依赖
bun install

# 3. 生成本地 CA 并信任（HTTPS 由 Caddy 在 keeper.localhost 提供）
mkdir -p .pki
openssl req -x509 -new -nodes \
  -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
  -keyout .pki/root.key -out .pki/root.crt \
  -days 3650 -subj "/CN=Keeper.sh CA"

# macOS 信任
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain .pki/root.crt
# Debian/Ubuntu 信任
sudo cp .pki/root.crt /usr/local/share/ca-certificates/keeper-dev-root.crt
sudo update-ca-certificates

# 4. 起服务（启动 Postgres + Redis + Caddy + API/Web/MCP/Cron/Worker）
bun dev

# 5. 访问 https://keeper.localhost

bun dev 会启动以下端口映射的服务：

服务 本地端口 访问路径
Caddy 443 https://keeper.localhost
Web 5173 （被 Caddy 反代）
API 3000 /api
MCP 3001 /mcp
Postgres 5432 postgresql://postgres:postgres@localhost:5432/postgres
Redis 6379 redis://localhost:6379

.localhost TLD 按 RFC 6761 自动解析到 127.0.0.1，无需修改 /etc/hosts。

四、核心用法

1. 配一个 Source（来源日历）

在 Web UI 的 "Sources" 页面选 Add：

  • Google / Outlook / iCloud / Fastmail / CalDAV：选 OAuth 流程授权
  • iCal / ICS URL：粘贴公开或半公开 ICS 链接（只读，不能作为 destination）

授权后 keeper.sh 会立刻拉一次全量，然后切到增量（Google sync token / Outlook delta link）。

2. 配一个 Sync Mapping（同步映射）

在 "Mappings" 页面选 Create：

  • 选 Source：某个已连接的来源日历
  • 选 Destination：某个目标日历（同样支持 Google/Outlook/iCloud/Fastmail/CalDAV）
  • 选字段：title / description / location / attendees
  • 选 Privacy：是否用 {{calendar_name}} 模板替换标题，避免把"看牙医"这种细节推到工作日历

3. 触发即时同步

curl -X POST https://keeper.example.com/api/v1/sync \
  -H "Authorization: Bearer $KEEPER_TOKEN"

或在 MCP 客户端调用 trigger_sync。后端行为：清掉 ingest 退避 → 下一轮轮询立即重拉源 → 入队 push 半段，限速 1 次/分钟/用户（防止被 provider 限流）。

4. 让 AI Agent 操作日历

把 keeper.sh 的 MCP endpoint 接进 Claude Desktop / Cherry Studio：

{
  "mcpServers": {
    "keeper": {
      "url": "https://keeper.example.com/mcp",
      "transport": "streamable-http"
    }
  }
}

MCP server 暴露的核心工具（按 keeper.sh 文档整理）：

  • list_calendars 列出所有已连接日历
  • query_events 按时间范围查事件
  • create_event 在指定日历创建事件
  • update_event 改事件（标题/时间/描述）
  • delete_event 删事件（只删 keeper.sh 自己创建的事件）
  • trigger_sync 立即触发一次双向同步
  • pause_sync / resume_sync 暂停/恢复某日历同步

5. 订阅统一 iCal Feed

所有已连接日历的合并 feed：

https://keeper.example.com/api/v1/feed/combined.ics

任何支持 ICS 订阅的日历 app（Apple Calendar / Thunderbird / Outlook.com）都可以把这个 URL 粘进去，keeper.sh 自己就是订阅源——你不再需要把 5 个 iCloud + 3 个 Google 日历分别订阅到一个 app 里。

6. 启用 Realtime Push（可选，Pro 功能）

设置环境变量 WEBHOOK_PUBLIC_URL=https://keeper.example.com，Google Calendar 和 Microsoft Graph 就能向你注册 webhook，几秒内就能感知日历变更（默认是 1 分钟轮询）。WEBHOOK_PUBLIC_URL 必须是公网 https 且不带 query/fragment——localhost、私有地址、.local 域名都会在启动时被拒。

五、典型适用场景

  • 多日历用户（个人）：工作 / 个人 / 副业分三个日历，keeper.sh 帮你把"个人忙"投到"工作日历"，避免同事在你健身时段约会议。
  • 跨生态用户：Google + iCloud + Outlook 同时在用，每次手动同步烦死。keeper.sh 做后台 cron，自动拉 + 自动推。
  • AI Agent 重度用户：让 Claude / 自定义 Agent 通过 MCP 直接管理你的日历——"帮我把这周三所有内部会议挪到周四下午"。没有 keeper.sh 之前这要做 3 个 OAuth 集成。
  • 隐私敏感团队：自托管版把所有日历数据留在自己服务器。AGPL-3.0 保证任何修改/衍生作品也必须开源。
  • 自由职业者 / 多公司顾问：每个客户给一个日历地址，自己的"总览日历"通过 keeper.sh 把所有客户日历的忙闲时段汇总显示，只共享 free/busy 不共享标题。
  • 企业 IT：可以给团队部署一个内网版 keeper.sh，让整个部门用统一日历视图。

六、坑与注意

  1. OAuth app 需要自己注册：Google Calendar / Microsoft Graph 都不允许"借用第三方 OAuth app"——你必须去 Google Cloud Console 和 Azure Portal 自建 OAuth client，把 client id/secret 填进 keeper.sh 的环境变量。官方云托管版帮你做了这件事；自托管必须自己来。
  2. Realtime Push 必须有公网 HTTPS：locahost / 私有 IP / .local 在启动校验时会被拒。内网部署想用 Push 功能必须配反代 + 域名 + 证书。
  3. AGPL-3.0 不是 MIT：自托管没问题，但如果你修改 keeper.sh 并对外提供服务（包括内网 SaaS），必须开源你的修改。商业用户请让法务过一遍。
  4. 删除行为是"只删 keeper.sh 自己创建的事件"：cleanup sweep 不会动你手动建的事件。这是设计而非 bug，但第一次用容易误以为"为什么我手动建的事件没被清理"——它本来就不会被清理。
  5. Free 层的限速：30 分钟刷新间隔 + 2 linked accounts + 3 sync mappings + 25 API/天。多账号或高频 API 用户直接上 Pro 或自托管。
  6. POST /api/v1/sync 会全局清退避：高并发场景下被 provider 限流的风险反而上升。生产环境建议自带节流。
  7. MCP_PUBLIC_URL 限制：必须公网 https。如果只想在本地 IDE 接 MCP，要把 API 的 BETTER_AUTH_URL 设成公网 URL（自签名证书在很多 MCP 客户端会被拒）。
  8. 旧版迁移：从老的 Next.js 版本升级需要看 migration guide #140——环境变量命名有变化。新版 Web 服务启动时会自动检测旧变量并打印 migration 提示。
  9. BLOCK_PRIVATE_RESOLUTION 默认 false：为了兼容内网 CalDAV/ICS 场景，默认允许 SSRF。对外暴露 keeper.sh 时务必手动设 true。
  10. v2.13.5 是 2026-07 第三方评测里的版本号：作者更新节奏是"几乎每周"，具体当前 release tag 请到 https://github.com/ridafkih/keeper.sh/releases 看。

七、与同类对比

工具 协议 同步源 AI Agent 接口 自托管 增量同步
keeper.sh AGPL-3.0 Google / Outlook / iCloud / Fastmail / CalDAV / iCal/ICS ✅（MCP 内建） ✅ ✅（Google sync token / Outlook delta link）
SyncGene 商业 / 闭源 Google / Outlook / iCloud / Yahoo ❌ ❌ ⚠️
CalendarBridge 商业 / 闭源 同上 ❌ ❌ ⚠️
google-calendar-sync（自建脚本） MIT（看具体项目） 仅 Google ❌ ✅ 视实现
radicale + 自写脚本 GPLv3 CalDAV 通用 ❌ ✅ ❌（需自己写）
Cloudflare Workers + D1 自建 MIT（自写） 看实现 ❌ ✅ 看实现

最强差异点：在"开源 + 自托管 + MCP + 增量同步"四个维度上全部齐备的，目前 keeper.sh 是少见的同时具备这几项的方案。

八、一句话推荐结论

对多日历用户与 AI Agent 重度使用者来说，keeper.sh 是当下最完整的开源日历同步 + MCP 方案——免费云托管试水、自托管解锁全部 Pro 功能。如果你只想解决"两个日历错峰"，继续用现成的导入/导出；如果你要让 Agent 直接动你的日历、又不想把数据交给第三方 SaaS，keeper.sh 几乎是当下唯一同时满足"开源 + MCP + 增量同步"的选择。