keeper.sh

MCP办公协作

提供方 ridafkih · 包名 keeper.sh

办公协作 stdio · 本地进程 未标注 社区 / 第三方 Claude DesktopCursorClineClaude Code
查看接入方式

Open-source calendar sync tool & universal calendar MCP server. Aggregate, sync and control calendars on Google, Outlook, Office 365, iCloud, CalDAV o

一句话选型结论

按资料字段整理

keeper.sh 属于办公协作类 MCP 服务器,stdio · 本地进程,鉴权方式未标注,可直接接入 Claude Desktop、Cursor、Cline 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类办公协作 传输方式stdio · 本地进程 鉴权未标注 部署方式本地部署
GitHub 星标 988 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

办公协作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

keeper.sh bun caldav calendar calendar-sync

支持客户端

适用场景

keeper.shbuncaldav

安装与配置

stdio · 本地进程 未标注
客户端在本机拉起子进程,数据不出本机
npx -y keeper.sh

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Cross-platform,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
日程与消息

查日程、发消息、约会议。

表单与审批

填表单、走审批流。

团队协作

同步任务、汇总进展。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Cursor、Cline,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在办公协作场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
keeper.sh当前 未标注 stdio · 本地进程 本地部署 有 2026-04-12
CowAgent 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Karakeep MCP 未标注 未标注 未标注 无 2026-05-17
agentscope 未标注 stdio · 本地进程 本地部署 有 2026-04-11
note-gen 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Everywhere 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

办公协作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方ridafkih上游标注的维护方 ridafkih
分类办公协作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式未标注远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时keeper.sh · Cross-platform本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-04-12上游最后核验时间

详细介绍

50.1 KB
来自项目仓库与上游目录的原文,未做删改

About

Keeper.sh is a simple & open-source calendar syncing tool. It allows you to pull events from your Google Calendar, Outlook, iCloud, Fastmail, CalDAV server, or remotely hosted iCal and ICS links, and push them to one or many calendars so the time slots can align across them all. Google, Outlook, iCloud, Fastmail, and CalDAV are first-class integrations that can each be used as a source or as a destination, while iCal and ICS links are pull-only. It also serves as a global MCP server and API for you or your agents to manage all your calendars from one convenient interface.

The recommended way to run it is the hosted version at keeper.sh: the same code, minus the server, the domain, the upgrades, the backups and the Google and Microsoft sign-in apps you would otherwise register yourself. Self-hosting is a first-class path and every Pro feature is included when you self-host — that is not a trial, and it is not going away. It costs you the upkeep instead of the $5.

Features

  • First-class Google Calendar, Outlook, iCloud, Fastmail, and CalDAV integrations, each usable as a source or a destination
  • Pull-only ingestion of remotely hosted iCal and ICS links
  • Incremental syncing on Google and Outlook using provider sync tokens rather than refetching everything
  • Event content agnostic syncing engine
  • Push aggregate events to one or more calendars
  • Per-source privacy controls to strip event names, descriptions, and locations, replacing the title with a {{calendar_name}} or {{event_name}} template
  • REST API under /api/v1 authenticated with API tokens
  • MCP (Model Context Protocol) server for AI agent calendar access
  • Combined iCal feed you can subscribe to from any calendar app
  • Open source under AGPL-3.0
  • Easy to self-host
  • Easy-to-purge remote events

Bug Reports & Feature Requests

If you encounter a bug or have an idea for a feature, you may open an issue on GitHub and it will be triaged and addressed as soon as possible.

Contributing

High-value and high-quality contributions are appreciated. Before working on large features you intend to see merged, please open an issue first to discuss beforehand.

Local Development

The dev environment runs behind HTTPS at https://keeper.localhost using a Caddy reverse proxy with automatic TLS. The .localhost TLD resolves to 127.0.0.1 automatically per RFC 6761 — no /etc/hosts entry is needed.

Prerequisites

  • Bun (v1.3.11+)
  • Docker & Docker Compose

Getting Started```bash

bun install


#### Generate and Trust a Root CA

The dev environment runs behind HTTPS via Caddy. You need to generate a local root certificate authority and trust it so your browser accepts the certificate.```bash
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"

Then trust it on your platform:

macOS```bash
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain .pki/root.crt


**Linux**```bash
sudo cp .pki/root.crt /usr/local/share/ca-certificates/keeper-dev-root.crt
sudo update-ca-certificates

Start the Dev Environment```bash

bun dev


This starts PostgreSQL, Redis, and a Caddy reverse proxy via Docker Compose, along with the API, web, MCP, cron, and worker services locally. Once running, open `https://keeper.localhost`.

### Architecture

| Service  | Local Port | Accessed Via                         |
| -------- | ---------- | ------------------------------------ |
| Caddy    | 443        | `https://keeper.localhost`           |
| Web      | 5173       | Proxied by Caddy                     |
| API      | 3000       | Proxied by Web at `/api`             |
| MCP      | 3001       | Proxied by Web at `/mcp`             |
| Postgres | 5432       | `postgresql://postgres:postgres@localhost:5432/postgres` |
| Redis    | 6379       | `redis://localhost:6379`             |

# Qs

## Why does this exist?

Because I needed it. Ever since starting Sedna—the AI governance platform—I've had to work across three calendars. One for my business, one for work, and one for personal.

Meetings have landed on top of one-another a frustratingly high number of times.

## Why not use _this other service_?

Use one if it already works for you. This one exists because of the two things I kept hitting: events deleted at the source that stayed on the destination forever, and no way to read the code that was handling my calendar.

Both are addressed by design here. A deletion is tracked by a mapping row that outlives the event it pointed at, so the remote copy still gets removed on a later pass, and the cleanup sweep only ever touches events Keeper.sh created — it will not delete an event you made yourself. And the engine is AGPL-3.0, so you can check that claim rather than take it.

## How does the syncing engine work?

- If we have a local event but no corresponding "source → destination" mapping for an event, we push the event to the destination calendar.
- If we have a mapping for an event, but the source ID is not present on the source any longer, we delete the event from the destination.
- Any events with markers of having been created by Keeper.sh, but with no corresponding local tracking, we remove it. This is only done for backwards compatibility.

Events are flagged as having been created by Keeper.sh either using a `@keeper.sh` suffix on the remote UID, or in the case of a platform like Outlook that doesn't support custom UIDs, we just put it in a `"keeper.sh"` category.

## How is the syncing split up?

There are two halves, and they run on separate schedules.

Ingestion pulls from your sources into Keeper.sh's own database once a minute, regardless of plan. Google and Outlook are fetched incrementally using the provider's own sync token and delta link respectively, so a run only asks for what changed since the last one. CalDAV, iCloud, and Fastmail are refetched and diffed against the event state Keeper.sh already has stored, and iCal/ICS links are refetched and diffed against the last stored snapshot.

Pushing to destinations is what the refresh interval in the pricing table refers to. The cron service enqueues a job per destination onto a Redis-backed queue every minute for Pro and every thirty minutes for free, and the worker service reconciles the destination calendar. This is polling on our side rather than provider push notifications, so nothing needs to reach your instance from the outside.

Neither half is schedule-only. `POST /api/v1/sync`, or `trigger_sync` over MCP, clears the ingest backoff so your sources are re-polled on the next pass and enqueues the push half straight away, throttled to one request per minute per user so a client cannot hammer your providers. A calendar paused with `pause_sync` is skipped by both halves until it is resumed.

# Cloud Hosted

This is the version I would point most people at, including people perfectly capable of running it themselves. It is the same engine on hardware I keep running, so the hours go into your calendar instead of your infrastructure — and paying for it is what funds the work on both versions.

Head to keeper.sh to get started with the cloud-hosted version.

|                             | Free       | Pro (Cloud-Hosted) | Pro (Self-Hosted) |
| --------------------------- | ---------- | ------------------ | ----------------- |
| **Monthly Price**           | $0 USD     | $5 USD             | $0                |
| **Annual Price**            | $0 USD     | $45 USD (-25%)     | $0                |
| **Refresh Interval**        | 30 minutes | 1 minute           | 1 minute          |
| **Linked Account Limit**    | 2          | ∞                  | ∞                 |
| **Sync Mapping Limit**      | 3          | ∞                  | ∞                 |
| **Event Filters**           | No         | Yes                | Yes               |
| **iCal Feed Customization** | No         | Yes                | Yes               |
| **API Requests**            | 25 per day | ∞                  | ∞                 |

The two limits that bite first are counted separately. A linked account is one connected Google, Outlook, iCloud, Fastmail, or CalDAV account, or one iCal/ICS subscription, and free is capped at two of them however many calendars each exposes. A sync mapping is one source calendar wired to one destination calendar, and free is capped at three, so a single source fanning out to three destinations uses the whole allowance. The refresh interval is how often Keeper.sh pushes to your destinations; ingestion from your sources runs every minute on every plan.

# Self Hosted

By hosting Keeper.sh yourself, you are on the Pro tier by default — every Pro feature, no subscription — and you can guarantee data governance and autonomy, and it's fun. What it costs instead is a server, a domain, upgrades, backups, your own Google and Microsoft OAuth apps, and being the person paged when it stops. If you'll be self-hosting, please consider supporting me and development of the project by sponsoring me on GitHub.

There are seven images currently available: two designed for convenience, and five that serve the granular underlying services. If you have no reason to prefer otherwise, start with `keeper-standalone` behind a reverse proxy — it is the path with the fewest moving parts to get wrong.

> [!NOTE]
>
> **Migrating from a previous version?** If you are upgrading from the older Next.js-based release, see the migration guide for environment variable changes. The new web server will also print a migration notice at startup if it detects old environment variables.

## Environment Variables

| Name                           | Service(s)    | Description                                                                                                                                                         |
| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DATABASE_URL                   | `api`, `cron`, `worker`, `mcp` | PostgreSQL connection URL.

e.g. `postgres://user:pass@postgres:5432/keeper`                                                                                  |
REDIS_URL · `api`, `cron`, `worker` · Redis connection URL. Must be the same Redis instance across all services.

e.g. `redis://redis:6379`                                                        |
DATABASE_POOL_MAX · `api`, `cron`, `worker`, `mcp` · Optional. Maximum Postgres connections the service's pool opens. Defaults to `10` per service, and the `keeper-standalone` and `keeper-services` images ship a smaller per-service value sized to the Postgres they run against. Every co-located service adds its own pool, so the sum of these plus `CRON_FLUSH_POOL_MAX` must stay under your Postgres `max_connections` with room left to connect for yourself.

e.g. `15` |
CRON_FLUSH_POOL_MAX · `cron` · Optional. Size of the second pool cron holds for ingest writes, separate from and additional to `DATABASE_POOL_MAX`. Defaults to `16`; the bundled images ship `8`.

e.g. `16` |
RUN_MIGRATIONS · `api` · Optional. Set to `false` to skip applying database migrations when the API container starts, for deployments that run them as a separate step before rolling the services. Defaults to `true`.

e.g. `false` |
WORKER_JOB_QUEUE_ENABLED · `cron` · Required. Set to `true` to enqueue sync jobs to the worker queue. Setting `false` stops the cron service from enqueuing destination syncs, so source events are still ingested but never pushed to destination calendars. If unset, the cron service will exit with a migration notice.
WORKER_CONCURRENCY · `worker` · Optional. Number of sync jobs the worker processes concurrently. Defaults to `25`.
BETTER_AUTH_URL · `api`, `mcp` · The base URL used for auth redirects.

e.g. `http://localhost:3000`                                                                                           |
BETTER_AUTH_SECRET · `api`, `mcp` · Secret key for session signing.

e.g. `openssl rand -base64 32`                                                                                               |
API_PORT · `api` · Required. Port the Bun API listens on. Pre-set to `3001` in the `keeper-standalone` and `keeper-services` images.
ENV · `web` · Optional. Runtime environment. One of `development`, `production`, or `test`. Defaults to `production`.
PORT · `web` · Required. Port the web server listens on. Pre-set to `3000` in the `keeper-standalone` and `keeper-services` images.
VITE_API_URL · `web` · The URL the web server uses to proxy requests to the Bun API.

e.g. `http://api:3001`                                                                         |
COMMERCIAL_MODE · `api`, `cron`, `mcp`, `web` · Enable Polar billing flow. Set to `true` if using Polar for subscriptions.
POLAR_ACCESS_TOKEN · `api`, `cron` · Optional. Polar API token for subscription management.
POLAR_MODE · `api`, `cron` · Optional. Polar environment, `sandbox` or `production`.
POLAR_WEBHOOK_SECRET · `api` · Optional. Secret to verify Polar webhooks.
ENCRYPTION_KEY · `api`, `cron`, `worker` · Key for encrypting CalDAV credentials at rest.

e.g. `openssl rand -base64 32`                                                                                |
RESEND_API_KEY · `api` · Optional. API key for sending emails via Resend.
FEEDBACK_EMAIL · `api` · Optional. Address that in-app feedback submissions are emailed to. Requires `RESEND_API_KEY`.
PASSKEY_RP_ID · `api` · Optional. Relying party ID for passkey authentication.
PASSKEY_RP_NAME · `api` · Optional. Relying party display name for passkeys.
PASSKEY_ORIGIN · `api` · Optional. Origin allowed for passkey flows (e.g., `https://keeper.example.com`).
GOOGLE_CLIENT_ID · `api`, `cron`, `worker` · Optional. Required for Google Calendar integration.
GOOGLE_CLIENT_SECRET · `api`, `cron`, `worker` · Optional. Required for Google Calendar integration.
MICROSOFT_CLIENT_ID · `api`, `cron`, `worker` · Optional. Required for Microsoft Outlook integration.
MICROSOFT_CLIENT_SECRET · `api`, `cron`, `worker` · Optional. Required for Microsoft Outlook integration.
OIDC_ISSUER_URL · `api` · Optional. Issuer URL of an OIDC-compliant identity provider (Authentik, Keycloak, Pocket ID, ...), exactly as the provider publishes it. Discovery is read from `/.well-known/openid-configuration`. Requires `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET`.

e.g. `https://id.example.com` or `https://auth.example.com/realms/keeper`                                                                              |
OIDC_CLIENT_ID · `api` · Optional. OAuth client ID registered with the OIDC issuer.
OIDC_CLIENT_SECRET · `api` · Optional. OAuth client secret registered with the OIDC issuer.
OIDC_PROVIDER_NAME · `api` · Optional. Display name shown on the SSO login button. Defaults to `SSO`.

e.g. `Pocket ID`                                                                      |
OIDC_SCOPES · `api` · Optional. Comma-separated scopes to request from the OIDC issuer. Defaults to `openid,profile,email`.

e.g. `openid,profile,email,groups`                                                                                    |
DISABLE_LOCAL_AUTH · `api` · Optional. Set to `true` to turn off username and email/password sign-in and sign-up. Google and Microsoft sign-in stay available while their client credentials are set. Only takes effect when `OIDC_ISSUER_URL`, `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET` are all set.
POSTGRES_PASSWORD · `standalone` · Optional. Custom password for the internal PostgreSQL database in `keeper-standalone`. If unset, defaults to `keeper`. The database is not exposed outside the container, so this is low risk, but can be set for defense in depth.
BLOCK_PRIVATE_RESOLUTION · `api`, `cron`, `worker` · Optional. Set to `true` to block outbound fetches (ICS subscriptions, CalDAV servers) from resolving to private/reserved network addresses. Prevents SSRF. Defaults to `false` for backward compatibility with self-hosted setups that use local CalDAV/ICS servers.
BLOCK_PRIVATE_RESOLUTION · `api`, `cron` · Optional. Set to `true` to block outbound fetches (ICS subscriptions, CalDAV servers) from resolving to private/reserved network addresses. Prevents SSRF. Defaults to `false` for backward compatibility with self-hosted setups that use local CalDAV/ICS servers.
REGISTRATION_EMAIL_DOMAINS · `api` · Optional. Comma-separated email domains that may create an account. When set, sign-up and first-time sign-in from any other domain are refused; existing accounts are unaffected. Unset or empty allows every domain.

e.g. `keeper.sh,example.com` |
TRUSTED_ORIGINS · `api` · Optional. Comma-separated list of additional trusted origins for CSRF protection.

e.g. `http://192.168.1.100,http://keeper.local,https://keeper.example.com` |
WEBHOOK_PUBLIC_URL · `api`, `cron` · Optional. Public HTTPS origin that Google Calendar and Microsoft Graph can reach your instance on. Setting it turns on realtime push, so Keeper.sh picks up calendar changes within seconds instead of waiting for the next poll. Leave it unset and nothing changes: polling continues exactly as before and no subscription is ever registered with a provider. Subscriptions are registered for every plan; on the free plan, notifications that arrive within five minutes of each other are folded into one read, and destinations still update on the free plan's 30-minute cadence. Must be a public `https://` origin with no query string or fragment — `localhost`, private-range and `.local` addresses are rejected at boot, since no provider could deliver to them.

e.g. `https://keeper.example.com` |
CRON_JOBS_ENABLED · `cron` · Optional. Set to `false` to run only the ingest loop in this process, for extra `cron` containers that add ingest capacity alongside the one that runs the scheduled jobs. Defaults to `true`.
INGEST_LOOP_ENABLED · `cron` · Optional. Set to `false` to stop this process from reading source calendars. Defaults to `true`. Any number of processes can run the loop at once: each claims the calendars that are due and holds them under a lease, so no calendar is read twice.
INGEST_FLEET_CONCURRENCY · `cron` · Optional. Calendars one process reads at once on their regular schedule. Defaults to `64`.
INGEST_WAKE_CONCURRENCY · `cron` · Optional. Calendars one process reads at once after a push notification, sync request or sign-in. Kept apart from the regular schedule so a backlog there never delays them. Defaults to `16`.
INGEST_CLAIM_BATCH · `cron` · Optional. Most calendars one process claims per query. Defaults to `50`.
INGEST_FLEET_IDLE_MS · `cron` · Optional. How long the loop waits before looking again when no calendar is due. Defaults to `2000`.
INGEST_WAKE_IDLE_MS · `cron` · Optional. The same wait for push notifications and other wakes. Defaults to `1000`.
INGEST_LEASE_SECONDS · `cron` · Optional. How long a claimed calendar stays with the process that claimed it. A calendar whose process dies is read again once its lease runs out. Defaults to `900`.
INGEST_PRO_POLL_SECONDS · `cron` · Optional. How often a Pro calendar is read when no healthy push subscription covers it. Defaults to `60`.
INGEST_FREE_POLL_SECONDS · `cron` · Optional. The same interval for free calendars. Defaults to `600`.
INGEST_PRO_SAFETY_POLL_SECONDS · `cron` · Optional. How often a Pro calendar with a healthy push subscription is read anyway, to catch a notification the provider dropped. Defaults to `300`.
INGEST_FREE_SAFETY_POLL_SECONDS · `cron` · Optional. The same safety interval for free calendars. Defaults to `3600`.
INGEST_DORMANT_POLL_SECONDS · `cron` · Optional. How often a dormant calendar is read: one that feeds no destination or feed, owned by someone who has not signed in or used the API for `INGEST_DORMANT_AFTER_DAYS`. Signing in reads it at once. Defaults to `86400`.
INGEST_DORMANT_AFTER_DAYS · `cron` · Optional. Days of inactivity before a calendar counts as dormant. Set to `0` to never treat a calendar as dormant. Defaults to `30`.
GOOGLE_PROJECT_REQUESTS_PER_MINUTE · `api`, `cron`, `worker` · Optional. Most Google Calendar requests per minute for the whole Google Cloud project. Background work (reading source calendars, writing to destinations, registering push channels, rediscovering calendars) uses up to 90% of it; the rest is kept for requests a person is waiting on, such as connecting an account or creating an event through the API, which skip ahead of queued background work. Defaults to `10000`, Google's published per-project limit; set it to your project's quota if that differs. Set to `0` for no project-wide limit beyond Google's per-user one.
OUTLOOK_INGEST_REQUESTS_PER_MINUTE · `cron` · Optional. Most Microsoft Graph requests per minute across every process reading calendars. Microsoft Graph limits Outlook per mailbox, which Keeper.sh already paces, so this is unset by default and means no limit.
WEBSOCKET_URL · `api` · Optional. External URL clients should open the realtime socket against. When unset, clients connect to the API's own `/api/socket` path.

e.g. `wss://socket.keeper.example.com` |
MCP_PUBLIC_URL · `api`, `mcp` · Optional on `api`, required by `mcp`. Public URL of the MCP resource. Enables OAuth on the API and identifies the MCP server to clients. In `keeper-standalone` it defaults to `BETTER_AUTH_URL` with `/mcp` appended.

e.g. `https://keeper.example.com/mcp` |
VITE_MCP_URL · `web` · Optional. Internal URL the web server uses to proxy `/mcp` requests to the MCP service.

e.g. `http://mcp:3002`                                              |
OPENAI_APPS_CHALLENGE_TOKEN · `web` · Optional. Domain verification token from the OpenAI Platform plugin submission, served at `/.well-known/openai-apps-challenge`. Only needed when submitting the MCP server to the ChatGPT Plugins Directory.

e.g. `abc123` |
MCP_PORT · `mcp` · Required by `mcp`. Port the MCP server listens on. Pre-set to `3002` in the `keeper-standalone` image.

e.g. `3002`                                          |
MCP_API_URL · `api`, `mcp` · Optional. Internal URL used to reach the Keeper.sh API when serving MCP — for tool calls, and for fetching the signing keys that validate MCP tokens. Defaults to `BETTER_AUTH_URL`, which requires both services to be able to reach your instance's public URL. Pre-set to the bundled API in the `keeper-standalone` image.

e.g. `http://api:3001` |
OTEL_EXPORTER_OTLP_ENDPOINT · `api`, `cron`, `worker`, `mcp`, `web` · Optional. When set, enables forwarding structured logs to an OpenTelemetry collector. Each service runs under the `keeper-otelemetry` binary from `@keeper.sh/otelemetry`, which starts the service as a child process, forwards its output and stop signals, and does not affect application performance.

e.g. `https://otel-collector.example.com:4318` |
OTEL_EXPORTER_OTLP_PROTOCOL · `api`, `cron`, `worker`, `mcp`, `web` · Optional. Protocol used by the OTLP exporter. Defaults to `http/protobuf` per the OpenTelemetry spec.

e.g. `http/protobuf`, `grpc`, `http/json` |
OTEL_EXPORTER_OTLP_HEADERS · `api`, `cron`, `worker`, `mcp`, `web` · Optional. Headers sent with every OTLP export request. Use this for authentication (e.g. Basic auth or API keys).

e.g. `Authorization=Basic dXNlcjpwYXNz` |

The following environment variables are read by the `web` server at **runtime** and serialized into the page as public runtime configuration. All of them are optional.

| Name                              | Description                                                        |
| --------------------------------- | ------------------------------------------------------------------ |
| POLAR_PRO_MONTHLY_PRODUCT_ID      | Optional. Polar monthly product ID to power in-app upgrade links.  |
| POLAR_PRO_YEARLY_PRODUCT_ID       | Optional. Polar yearly product ID to power in-app upgrade links.   |
| VITE_VISITORS_NOW_TOKEN           | Optional. visitors.now token for analytics |
| VITE_GOOGLE_ADS_ID                | Optional. Google Ads conversion tracking ID (e.g., `AW-123456789`) |
| VITE_GOOGLE_ADS_CONVERSION_LABEL  | Optional. Google Ads conversion label for purchase tracking        |
| VITE_GOOGLE_ADS_SIGNUP_CONVERSION_LABEL | Optional. Google Ads conversion label for signup tracking     |
| VITE_GOOGLE_ANALYTICS_ID                | Optional. Google Analytics 4 measurement ID (e.g., `G-XXXXXXXXXX`) |

> [!NOTE]
>
> - `keeper-standalone` auto-configures everything internally — both the web server and Bun API sit behind a single Caddy reverse proxy on port `80`.
> - `keeper-services` runs the web, API, cron, and worker services inside one container. The web server proxies `/api` requests internally, so only port `3000` needs to be exposed.
> - For individual images, only the `web` container needs to be exposed. The API is accessed internally via `VITE_API_URL`.

## Images

| Tag                        | Description                                                                                                                                              | Included Services                                                                        |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `keeper-standalone:2`    | The "standalone" image is everything you need to get up and running with Keeper.sh with as little configuration as possible.                                | `keeper-web`, `keeper-api`, `keeper-cron`, `keeper-worker`, `keeper-mcp`, `redis`, `postgresql`, `caddy` |
| `keeper-services:2`      | If you'd like for the Redis & Database to exist outside of the container, you can use the "services" image to launch without them included in the image. | `keeper-web`, `keeper-api`, `keeper-cron`, `keeper-worker`                                 |
| `keeper-web:2`           | An image containing the Vite SSR web interface.                                                                                                          | `keeper-web`                                                                              |
| `keeper-api:2`           | An image containing the Bun API service.                                                                                                                 | `keeper-api`                                                                              |
| `keeper-cron:2`          | An image containing the Bun cron service. Requires `keeper-worker` for destination syncing.                                                              | `keeper-cron`                                                                             |
| `keeper-worker:2`        | An image containing the BullMQ worker that processes calendar sync jobs enqueued by `keeper-cron`.                                                       | `keeper-worker`                                                                           |
| `keeper-mcp:2`           | An image containing the MCP server for AI agent calendar access. Optional — only needed if using MCP clients.                                            | `keeper-mcp`                                                                              |

> [!TIP]
>
> Pin your images to a major.minor version tag (e.g., `2.13`) rather than `latest`. This prevents breaking changes from automatically applying when you pull new images.

## Prerequisites

### Docker & Docker Compose

In order to install Docker Compose, please refer to the official Docker documentation..

### Google OAuth Credentials

> [!TIP]
>
> This is optional, although you will not be able to set Google Calendar as a destination without this.

Reference the official Google Cloud Platform documentation to generate valid credentials for Google OAuth. You must grant your consent screen the `calendar.events`, `calendar.calendarlist.readonly`, and `userinfo.email` scopes.

Once this is configured, set the client ID and client secret as the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables at runtime.

### Microsoft Azure Credentials

> [!TIP]
>
> Once again, this is optional. If you do not configure this, you will not be able to configure Microsoft Outlook as a destination.

The clearest non-legacy walkthrough for configuring OAuth is this community thread.. The required scopes are `Calendars.ReadWrite`, `User.Read`, and `offline_access`. The client ID and secret for Microsoft go into the `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` environment variables respectively.

If people will sign in with work or school (Entra ID) accounts, add the `xms_edov` optional claim to the app registration under **Token configuration → Add optional claim → ID → `xms_edov`**. Entra sets it when the tenant has verified the domain of the account's email, and Keeper.sh uses it to record that email as verified. Without it, a work or school sign-in is recorded as unverified and can't be linked automatically to an existing account with the same email; it can still be linked from settings while signed in. Personal Microsoft accounts don't need the claim.

### OIDC / SSO

Self-hosters can delegate sign-in to any OIDC-compliant identity provider (Authentik, Keycloak, Pocket ID, Zitadel, ...). Nothing changes until the variables below are set.

Register a confidential client with your provider using this redirect URI:```
https://<your-keeper-origin>/api/auth/oauth2/callback/oidc

Then pass the client to the container running the API (keeper-standalone, keeper-services, or keeper-api):```yaml
environment:

…(正文过长,页面只展示前面部分,完整内容见仓库)
```

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
keeper.sh 怎么安装?

在客户端按下面的安装命令接入:npx -y keeper.sh。对应的包名是 keeper.sh。装完在客户端配置里引用同一个包或端点。

keeper.sh 怎么在 Claude Desktop、Cursor、Cline 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

keeper.sh 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

keeper.sh 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

keeper.sh 支持哪些客户端?

资料标注支持 Claude Desktop、Cursor、Cline、Claude Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

keeper.sh 能提供哪些能力?

资料显示能力标签包括 keeper.sh、bun、caldav、calendar、calendar-sync。具体工具清单以官方文档为准。

keeper.sh 需要什么运行环境?

运行时为 Cross-platform;属于本地进程,需要在本机装好运行环境。

keeper.sh 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-04-12。