Skip to content
Back to search

keeper.sh

Calendar sync tool & universal calendar MCP server. Aggregate, sync and control calendars on Google, Outlook, Office 365, iCloud, CalDAV or ICS.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ridafkih/keeper.sh with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ridafkih/keeper.sh'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ridafkih--keeper-sh/badge.svg)](/listings/ridafkih--keeper-sh)

HTML

<a href="/listings/ridafkih--keeper-sh"><img src="/api/listings/ridafkih--keeper-sh/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

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**

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

**Linux**

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

Start the Dev Environment

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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 796 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ![](./applications/web/public/open-graph.png)
  2. # About
  3. 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.
  4. The recommended way to run it is the hosted version at [keeper.sh](https://www.keeper.sh/register): 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 $9.
  5. # Features
  6. - First-class Google Calendar, Outlook, iCloud, Fastmail, and CalDAV integrations, each usable as a source or a destination
  7. - Pull-only ingestion of remotely hosted iCal and ICS links
  8. - Incremental syncing on Google and Outlook using provider sync tokens rather than refetching everything
  9. - Event content agnostic syncing engine
  10. - Push aggregate events to one or more calendars
  11. - Per-source privacy controls to strip event names, descriptions, and locations, replacing the title with a `{{calendar_name}}` or `{{event_name}}` template
  12. - REST API under `/api/v1` authenticated with API tokens
  13. - MCP (Model Context Protocol) server for AI agent calendar access
  14. - Combined iCal feed you can subscribe to from any calendar app
  15. - Open source under AGPL-3.0
  16. - Easy to self-host
  17. - Easy-to-purge remote events
  18. # Bug Reports & Feature Requests
  19. If you encounter a bug or have an idea for a feature, you may [open an issue on GitHub](https://github.com/ridafkih/keeper.sh/issues) and it will be triaged and addressed as soon as possible.
  20. # Contributing
  21. 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.
  22. ## Local Development
  23. The dev environment runs behind HTTPS at `https://keeper.localhost` using a [Caddy](https://caddyserver.com/) reverse proxy with automatic TLS. The `.localhost` TLD resolves to `127.0.0.1` automatically per [RFC 6761](https://datatracker.ietf.org/doc/html/rfc6761) — no `/etc/hosts` entry is needed.
  24. ### Prerequisites
  25. - [Bun](https://bun.sh/) (v1.3.11+)
  26. - [Docker](https://docs.docker.com/get-started/) & Docker Compose
  27. ### Getting Started
  28. ```bash
  29. bun install
  30. ```
  31. #### Generate and Trust a Root CA
  32. 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.
  33. ```bash
  34. mkdir -p .pki
  35. openssl req -x509 -new -nodes \
  36. -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
  37. -keyout .pki/root.key -out .pki/root.crt \
  38. -days 3650 -subj "/CN=Keeper.sh CA"
  39. ```
  40. Then trust it on your platform:
  41. **macOS**
  42. ```bash
  43. sudo security add-trusted-cert -d -r trustRoot \
  44. -k /Library/Keychains/System.keychain .pki/root.crt
  45. ```
  46. **Linux**
  47. ```bash
  48. sudo cp .pki/root.crt /usr/local/share/ca-certificates/keeper-dev-root.crt
  49. sudo update-ca-certificates
  50. ```
  51. #### Start the Dev Environment
  52. ```bash
  53. bun dev
  54. ```
  55. 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`.
  56. ### Architecture
  57. | Service | Local Port | Accessed Via |
  58. | -------- | ---------- | ------------------------------------ |
  59. | Caddy | 443 | `https://keeper.localhost` |
  60. | Web | 5173 | Proxied by Caddy |
  61. | API | 3000 | Proxied by Web at `/api` |
  62. | MCP | 3001 | Proxied by Web at `/mcp` |
  63. | Postgres | 5432 | `postgresql://postgres:postgres@localhost:5432/postgres` |
  64. | Redis | 6379 | `redis://localhost:6379` |
  65. # Qs
  66. ## Why does this exist?
  67. Because I needed it. Ever since starting [Sedna](https://sedna.sh/)—the AI governance platform—I've had to work across three calendars. One for my business, one for work, and one for personal.
  68. Meetings have landed on top of one-another a frustratingly high number of times.
  69. ## Why not use _this other service_?
  70. 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.
  71. 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.
  72. ## How does the syncing engine work?
  73. - If we have a local event but no corresponding "source → destination" mapping for an event, we push the event to the destination calendar.
  74. - 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.
  75. - 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.
  76. 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.
  77. ## How is the syncing split up?
  78. There are two halves, and they run on separate schedules.
  79. 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.
  80. 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.
  81. 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.
  82. # Cloud Hosted
  83. 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.
  84. Head to [keeper.sh](https://www.keeper.sh/register) to get started with the cloud-hosted version.
  85. | | Free | Pro (Cloud-Hosted) | Pro (Self-Hosted) |
  86. | --------------------------- | ---------- | ------------------ | ----------------- |
  87. | **Monthly Price** | $0 USD | $9 USD | $0 |
  88. | **Annual Price** | $0 USD | $79 USD (-27%) | $0 |
  89. | **Refresh Interval** | 30 minutes | 1 minute | 1 minute |
  90. | **Linked Account Limit** | 2 | ∞ | ∞ |
  91. | **Sync Mapping Limit** | 3 | ∞ | ∞ |
  92. | **Event Filters** | No | Yes | Yes |
  93. | **iCal Feed Customization** | No | Yes | Yes |
  94. | **API Requests** | 25 per day | ∞ | ∞ |
  95. 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.
  96. # Self Hosted
  97. 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.
  98. 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.
  99. > [!NOTE]
  100. >
  101. > **Migrating from a previous version?** If you are upgrading from the older Next.js-based release, see the [migration guide](https://github.com/ridafkih/keeper.sh/issues/140) for environment variable changes. The new web server will also print a migration notice at startup if it detects old environment variables.
  102. ## Environment Variables
  103. | Name | Service(s) | Description |
  104. | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  105. | DATABASE_URL | `api`, `cron`, `worker`, `mcp` | PostgreSQL connection URL.<br><br>e.g. `postgres://user:pass@postgres:5432/keeper` |
  106. | REDIS_URL | `api`, `cron`, `worker` | Redis connection URL. Must be the same Redis instance across all services.<br><br>e.g. `redis://redis:6379` |
  107. | 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.<br><br>e.g. `15` |
  108. | 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`.<br><br>e.g. `16` |
  109. | 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`.<br><br>e.g. `false` |
  110. | 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. |
  111. | WORKER_CONCURRENCY | `worker` | Optional. Number of sync jobs the worker processes concurrently. Defaults to `25`. |
  112. | BETTER_AUTH_URL | `api`, `mcp` | The base URL used for auth redirects.<br><br>e.g. `http://localhost:3000` |
  113. | BETTER_AUTH_SECRET | `api`, `mcp` | Secret key for session signing.<br><br>e.g. `openssl rand -base64 32` |
  114. | API_PORT | `api` | Required. Port the Bun API listens on. Pre-set to `3001` in the `keeper-standalone` and `keeper-services` images. |
  115. | ENV | `api`, `cron`, `worker`, `mcp`, `web` | Required. Runtime environment. One of `development`, `production`, or `test`. Pre-set to `production` in the published images. |
  116. | COMMIT_SHA | `api`, `cron`, `worker`, `mcp`, `web` | Required. The git commit the service was built from, recorded on every log event. Baked into the published images; `bun dev` and `bun run start` read it from git. When building an image yourself, pass `--build-arg COMMIT_SHA=$(git rev-parse HEAD)`. |
  117. | VERSION | `api`, `cron`, `worker`, `mcp`, `web` | Required. The release version the service was built from, recorded on every log event. Baked into the published images; `bun dev` and `bun run start` read it from git. When building an image yourself, pass `--build-arg VERSION=$(git describe --tags --always)`. |
  118. | PORT | `web` | Required. Port the web server listens on. Pre-set to `3000` in the `keeper-standalone` and `keeper-services` images. |
  119. | VITE_API_URL | `web` | The URL the web server uses to proxy requests to the Bun API.<br><br>e.g. `http://api:3001` |
  120. | COMMERCIAL_MODE | `api`, `cron`, `worker`, `mcp`, `web` | Enable Polar billing flow. Set to `true` if using Polar for subscriptions. Also turns `BLOCK_PRIVATE_RESOLUTION` on in `api`, `cron` and `worker`. |
  121. | POLAR_ACCESS_TOKEN | `api` | Optional. Polar API token for subscription management. |
  122. | POLAR_MODE | `api` | Optional. Polar environment, `sandbox` or `production`. |
  123. | POLAR_WEBHOOK_SECRET | `api` | Optional. Secret to verify Polar webhooks. |
  124. | ENCRYPTION_KEY | `api`, `cron`, `worker` | Key for encrypting CalDAV credentials at rest.<br><br>e.g. `openssl rand -base64 32` |
  125. | RESEND_API_KEY | `api` | Optional. API key for sending emails via Resend. |
  126. | FEEDBACK_EMAIL | `api` | Optional. Address that in-app feedback submissions are emailed to, through the `user-feedback` and `problem-report` Resend templates. Agent feedback received at `/api/v1/agent-feedback` goes to the same address through the `agent-feedback` template, under an `Agent feedback:` subject. Requires `RESEND_API_KEY`. |
  127. | PASSKEY_RP_ID | `api` | Optional. Relying party ID for passkey authentication. |
  128. | PASSKEY_RP_NAME | `api` | Optional. Relying party display name for passkeys. |
  129. | PASSKEY_ORIGIN | `api` | Optional. Origin allowed for passkey flows (e.g., `https://keeper.example.com`). |
  130. | GOOGLE_CLIENT_ID | `api`, `cron`, `worker` | Optional. Required for Google Calendar integration. |
  131. | GOOGLE_CLIENT_SECRET | `api`, `cron`, `worker` | Optional. Required for Google Calendar integration. |
  132. | MICROSOFT_CLIENT_ID | `api`, `cron`, `worker` | Optional. Required for Microsoft Outlook integration. |
  133. | MICROSOFT_CLIENT_SECRET | `api`, `cron`, `worker` | Optional. Required for Microsoft Outlook integration. |
  134. | 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 `<issuer>/.well-known/openid-configuration`. Requires `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET`.<br><br>e.g. `https://id.example.com` or `https://auth.example.com/realms/keeper` |
  135. | OIDC_CLIENT_ID | `api` | Optional. OAuth client ID registered with the OIDC issuer. |
  136. | OIDC_CLIENT_SECRET | `api` | Optional. OAuth client secret registered with the OIDC issuer. |
  137. | OIDC_PROVIDER_NAME | `api` | Optional. Display name shown on the SSO login button. Defaults to `SSO`.<br><br>e.g. `Pocket ID` |
  138. | OIDC_SCOPES | `api` | Optional. Comma-separated scopes to request from the OIDC issuer. Defaults to `openid,profile,email`.<br><br>e.g. `openid,profile,email,groups` |
  139. | OIDC_TRUST_EMAIL_VERIFIED | `api` | Optional. Set to `true` to trust the OIDC provider's `email_verified` claim, so a sign-in links to an existing account with the same verified email. Defaults to `false`. Only enable it if your provider verifies every email address it asserts. |
  140. | 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. |
  141. | 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. |
  142. | 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. Always on when `COMMERCIAL_MODE` is `true`, whatever this is set to. Each service logs the effective setting once at startup. |
  143. | PRIVATE_RESOLUTION_WHITELIST | `api`, `cron`, `worker` | Optional. Comma-separated hosts that stay reachable while private addresses are blocked, matched against the host of the URL, including the port when the URL has one.<br><br>e.g. `nas.local:5232,192.168.1.20` |
  144. | 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.<br><br>e.g. `keeper.sh,example.com` |
  145. | TRUSTED_ORIGINS | `api` | Optional. Comma-separated list of additional trusted origins for CSRF protection.<br><br>e.g. `http://192.168.1.100,http://keeper.local,https://keeper.example.com` |
  146. | 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.<br><br>e.g. `https://keeper.example.com` |
  147. | 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`. |
  148. | 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. |
  149. | INGEST_FLEET_CONCURRENCY | `cron` | Optional. Calendars one process reads at once on their regular schedule. Defaults to `64`. |
  150. | 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`. |
  151. | INGEST_CLAIM_BATCH | `cron` | Optional. Most calendars one process claims per query. Defaults to `50`. |
  152. | INGEST_FLEET_IDLE_MS | `cron` | Optional. How long the loop waits before looking again when no calendar is due. Defaults to `2000`. |
  153. | INGEST_WAKE_IDLE_MS | `cron` | Optional. The same wait for push notifications and other wakes. Defaults to `1000`. |
  154. | 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`. |
  155. | INGEST_PRO_POLL_SECONDS | `cron` | Optional. How often a Pro calendar is read when no healthy push subscription covers it. Defaults to `60`. |
  156. | INGEST_FREE_POLL_SECONDS | `cron` | Optional. The same interval for free calendars. Defaults to `600`. |
  157. | 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`. |
  158. | INGEST_FREE_SAFETY_POLL_SECONDS | `cron` | Optional. The same safety interval for free calendars. Defaults to `3600`. |
  159. | 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`. |
  160. | 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`. |
  161. | 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. |
  162. | 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. |
  163. | 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.<br><br>e.g. `wss://socket.keeper.example.com` |
  164. | 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.<br><br>e.g. `https://keeper.example.com/mcp` |
  165. | VITE_MCP_URL | `web` | Optional. Internal URL the web server uses to proxy `/mcp` requests to the MCP service.<br><br>e.g. `http://mcp:3002` |
  166. | 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.<br><br>e.g. `abc123` |
  167. | MCP_PORT | `mcp` | Required by `mcp`. Port the MCP server listens on. Pre-set to `3002` in the `keeper-standalone` image.<br><br>e.g. `3002` |
  168. | 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.<br><br>e.g. `http://api:3001` |
  169. | AGENT_FEEDBACK_DISABLED | `mcp` | Optional. Set to `true` to turn agent feedback off for every user on the instance: `send_feedback` is not offered, tools give no hint to send feedback, and `intent` is not recorded. Defaults to on. Any value other than `true` or `false` stops the service at startup.<br><br>e.g. `true` |
  170. | OTEL_EXPORTER_OTLP_ENDPOINT | `api`, `cron`, `worker`, `mcp`, `web` | Optional. When set, enables forwarding structured logs and traces to an OpenTelemetry collector. Logs go through the `keeper-otelemetry` binary from [`@keeper.sh/otelemetry`](./packages/otelemetry), which starts the service as a child process, forwards its output and stop signals, and does not affect application performance. Traces are exported in-process to `/v1/traces` on the same endpoint from a bounded queue that drops spans rather than slowing requests down, and every wide event carries the `trace_id` and `span_id` of its trace.<br><br>e.g. `https://otel-collector.example.com:4318` |
  171. | TRACE_SAMPLE_RATIO | `api`, `cron`, `worker`, `mcp`, `web` | Optional. Share of new traces exported when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, between `0` and `1`. Downstream services follow the decision made where the trace started. Traces that end in an error or run longer than `TRACE_SLOW_THRESHOLD_MS` are exported regardless. Defaults to `0.1`.<br><br>e.g. `0.25` |
  172. | TRACE_SLOW_THRESHOLD_MS | `api`, `cron`, `worker`, `mcp`, `web` | Optional. A request, job or ingest round that takes at least this long is exported even when the sample ratio left it out. Defaults to `2000`.<br><br>e.g. `5000` |
  173. | OTEL_EXPORTER_OTLP_PROTOCOL | `api`, `cron`, `worker`, `mcp`, `web` | Optional. Protocol used by the OTLP exporter. Defaults to `http/protobuf` per the OpenTelemetry spec.<br><br>e.g. `http/protobuf`, `grpc`, `http/json` |
  174. | 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).<br><br>e.g. `Authorization=Basic dXNlcjpwYXNz` |
  175. 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.
  176. | Name | Description |
  177. | --------------------------------- | ------------------------------------------------------------------ |
  178. | POLAR_PRO_MONTHLY_PRODUCT_ID | Optional. Polar monthly product ID to power in-app upgrade links. |
  179. | POLAR_PRO_YEARLY_PRODUCT_ID | Optional. Polar yearly product ID to power in-app upgrade links. |
  180. | VITE_VISITORS_NOW_TOKEN | Optional. [visitors.now](https://visitors.now) token for analytics |
  181. | VITE_GOOGLE_ADS_ID | Optional. Google Ads conversion tracking ID (e.g., `AW-123456789`) |
  182. | VITE_GOOGLE_ADS_CONVERSION_LABEL | Optional. Google Ads conversion label for purchase tracking |
  183. | VITE_GOOGLE_ADS_SIGNUP_CONVERSION_LABEL | Optional. Google Ads conversion label for signup tracking |
  184. | VITE_GOOGLE_ANALYTICS_ID | Optional. Google Analytics 4 measurement ID (e.g., `G-XXXXXXXXXX`) |
  185. > [!NOTE]
  186. >
  187. > - `keeper-standalone` auto-configures everything internally — both the web server and Bun API sit behind a single Caddy reverse proxy on port `80`.
  188. > - `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.
  189. > - For individual images, only the `web` container needs to be exposed. The API is accessed internally via `VITE_API_URL`.
  190. ## Images
  191. | Tag | Description | Included Services |
  192. | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
  193. | `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` |
  194. | `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` |
  195. | `keeper-web:2` | An image containing the Vite SSR web interface. | `keeper-web` |
  196. | `keeper-api:2` | An image containing the Bun API service. | `keeper-api` |
  197. | `keeper-cron:2` | An image containing the Bun cron service. Requires `keeper-worker` for destination syncing. | `keeper-cron` |
  198. | `keeper-worker:2` | An image containing the BullMQ worker that processes calendar sync jobs enqueued by `keeper-cron`. | `keeper-worker` |
  199. | `keeper-mcp:2` | An image containing the MCP server for AI agent calendar access. Optional — only needed if using MCP clients. | `keeper-mcp` |
  200. > [!TIP]
  201. >
  202. > 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.
  203. ## Prerequisites
  204. ### Docker & Docker Compose
  205. In order to install Docker Compose, please refer to the [official Docker documentation.](https://docs.docker.com/compose/install/).
  206. ### Google OAuth Credentials
  207. > [!TIP]
  208. >
  209. > This is optional, although you will not be able to set Google Calendar as a destination without this.
  210. Reference the [official Google Cloud Platform documentation](https://support.google.com/cloud/answer/15549257) to generate valid credentials for Google OAuth. You must grant your consent screen the `calendar.events`, `calendar.calendarlist.readonly`, and `userinfo.email` scopes.
  211. Once this is configured, set the client ID and client secret as the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables at runtime.
  212. ### Microsoft Azure Credentials
  213. > [!TIP]
  214. >
  215. > Once again, this is optional. If you do not configure this, you will not be able to configure Microsoft Outlook as a destination.
  216. The clearest non-legacy walkthrough for configuring OAuth is this [community thread.](https://learn.microsoft.com/en-us/answers/questions/4705805/how-to-set-up-oauth-2-0-for-outlook). 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.
  217. 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.
  218. ### OIDC / SSO
  219. 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.
  220. Register a confidential client with your provider using this redirect URI:
  221. ```
  222. https://<your-keeper-origin>/api/auth/oauth2/callback/oidc
  223. ```
  224. Then pass the client to the container running the API (`keeper-standalone`, `keeper-services`, or `keeper-api`):
  225. ```yaml
  226. environment:
  227. OIDC_ISSUER_URL: https://id.example.com
  228. OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
  229. OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
  230. OIDC_PROVIDER_NAME: Pocket ID
  231. ```
  232. `OIDC_ISSUER_URL` must match the `issuer` your provider publishes, including any path, such as `https://auth.example.com/realms/keeper` for Keycloak or `https://authentik.example.com/application/o/keeper/` for Authentik. `OIDC_PROVIDER_NAME` labels the sign-in button and defaults to `SSO`. `OIDC_SCOPES` is a comma-separated list that defaults to `openid,profile,email`.
  233. Signing in with the provider for the first time creates a new Keeper.sh account. By default it is never merged into an existing account automatically: if the provider's email address already belongs to a Keeper.sh account, the sign-in is refused instead. To move an existing account to SSO, sign in the usual way and choose **Link SSO** in settings; from then on either method signs in to the same account.
  234. If your provider verifies every email address it asserts, you can let sign-ins link to existing accounts automatically instead:
  235. ```yaml
  236. OIDC_TRUST_EMAIL_VERIFIED: "true"
  237. ```
  238. With this set, a sign-in links to an existing Keeper.sh account only when the provider sends `email_verified: true` for the address and the existing account's email is itself verified. Anything else, including a missing claim, is refused as before. Username accounts are never linked this way. Leave it off if users can set their own email at the provider without verifying it, since anyone able to claim an address there could then sign in to the matching Keeper.sh account.
  239. Once everyone who needs one has linked their account, you can turn off username and password sign-in:
  240. ```yaml
  241. DISABLE_LOCAL_AUTH: "true"
  242. ```
  243. This turns off username and password sign-in and sign-up on the server, not just in the interface. Google and Microsoft sign-in aren't affected: they stay available while `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET` or `MICROSOFT_CLIENT_ID`/`MICROSOFT_CLIENT_SECRET` are set, which calendar sync with those providers also needs. It only takes effect when the OIDC client is fully configured, so setting it alone can't lock you out.
  244. ## Standalone Container
  245. `keeper-standalone:2` is the recommended starting point for a single-instance deployment. This container contains the `cron`, `worker`, `web`, `api` services as well as a configured `redis`, `database`, and `caddy` instance that puts everything behind the same port. Split the services out later if you need to scale them independently, run your own Postgres and Redis, or place them on separate hosts.
  246. ### Generate `keeper-standalone` Environment Variables
  247. The following will generate a `.env` file that contains the key used to generate sessions, as well as the key that is used to encrypt CalDAV credentials at rest.
  248. > [!IMPORTANT]
  249. >
  250. > If you plan on accessing Keeper.sh from a URL _other than_ http://localhost,
  251. > you will need to set the `TRUSTED_ORIGINS` environment variable. This should
  252. > be a comma-delimited list of protocol-hostname inclusive origins you will be using.
  253. >
  254. > Here is an example where we would be accessing Keeper.sh from the LAN IP and where we
  255. > are routing Keeper.sh through a reverse proxy that hosts it at https://keeper.example.com/
  256. >
  257. > ```bash
  258. > TRUSTED_ORIGINS=http://10.0.0.2,https://keeper.example.com
  259. > ```
  260. >
  261. > Without this, you will fail CSRF checks on the `better-auth` package.
  262. ```bash
  263. cat > .env << EOF
  264. # BETTER_AUTH_SECRET and ENCRYPTION_KEY are required.
  265. # TRUSTED_ORIGINS is required if you plan on accessing Keeper.sh from an
  266. # origin other than http://localhost/
  267. BETTER_AUTH_SECRET=$(openssl rand -base64 32)
  268. ENCRYPTION_KEY=$(openssl rand -base64 32)
  269. TRUSTED_ORIGINS=
  270. GOOGLE_CLIENT_ID=
  271. GOOGLE_CLIENT_SECRET=
  272. MICROSOFT_CLIENT_ID=
  273. MICROSOFT_CLIENT_SECRET=
  274. EOF
  275. ```
  276. ### Run `keeper-standalone` with Docker
  277. If you'd like to just run using the Docker CLI, you can use the following command. I would however recommend [using a compose.yaml](#run-standalone-with-docker-compose) file.
  278. ```bash
  279. docker run -d \
  280. -p 80:80 \
  281. -v keeper-data:/var/lib/postgresql/data \
  282. --env-file .env \
  283. ghcr.io/ridafkih/keeper-standalone:2
  284. ```
  285. ### Run `keeper-standalone` with Docker Compose
  286. If you'd prefer to use a `compose.yaml` file, the following is an example. Remember to [populate your .env file first](#generate-keeper-standalone-environment-variables).
  287. ```yaml
  288. services:
  289. keeper:
  290. image: ghcr.io/ridafkih/keeper-standalone:2
  291. ports:
  292. - "80:80"
  293. volumes:
  294. - keeper-data:/var/lib/postgresql/data
  295. environment:
  296. BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
  297. ENCRYPTION_KEY: ${ENCRYPTION_KEY}
  298. TRUSTED_ORIGINS: ${TRUSTED_ORIGINS}
  299. GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
  300. GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
  301. MICROSOFT_CLIENT_ID: ${MICROSOFT_CLIENT_ID:-}
  302. MICROSOFT_CLIENT_SECRET: ${MICROSOFT_CLIENT_SECRET:-}
  303. volumes:
  304. keeper-data:
  305. ```
  306. Once that's configured, you can launch Keeper.sh using the following command.
  307. ```bash
  308. docker compose up -d
  309. ```
  310. With all said and done, you can access Keeper.sh at http://localhost/. You can use a reverse-proxy like Nginx or Caddy to put Keeper.sh behind a domain on your network.
  311. ## Collective Services Image
  312. If you'd like to bring your own Redis and PostgreSQL, you can use the `keeper-services` image. This contains the `cron`, `worker`, `web` and `api` services in one.
  313. ### Generate `keeper-services` Environment Variables
  314. ```bash
  315. cat > .env << EOF
  316. # DATABASE_URL and REDIS_URL are required.
  317. # *_CLIENT_ID and *_CLIENT_SECRET are optional.
  318. BETTER_AUTH_SECRET=$(openssl rand -base64 32)
  319. ENCRYPTION_KEY=$(openssl rand -base64 32)
  320. DATABASE_URL=postgres://keeper:keeper@postgres:5432/keeper
  321. REDIS_URL=redis://redis:6379
  322. BETTER_AUTH_URL=http://localhost:3000
  323. GOOGLE_CLIENT_ID=
  324. GOOGLE_CLIENT_SECRET=
  325. MICROSOFT_CLIENT_ID=
  326. MICROSOFT_CLIENT_SECRET=
  327. EOF
  328. ```
  329. ### Run `keeper-services` with Docker Compose
  330. Once you've populated your environment variables, you can choose to run `redis` and `postgres` alongside the `keeper-services` image to get up and running.
  331. ```yaml
  332. services:
  333. postgres:
  334. image: postgres:17
  335. command: ["postgres", "-c", "max_connections=200"]
  336. environment:
  337. POSTGRES_USER: keeper
  338. POSTGRES_PASSWORD: keeper
  339. POSTGRES_DB: keeper
  340. volumes:
  341. - postgres-data:/var/lib/postgresql/data
  342. healthcheck:
  343. test: ["CMD-SHELL", "pg_isready -U keeper -d keeper"]
  344. interval: 5s
  345. timeout: 5s
  346. retries: 5
  347. redis:
  348. image: redis:7-alpine
  349. volumes:
  350. - redis-data:/data
  351. healthcheck:
  352. test: ["CMD", "redis-cli", "ping"]
  353. interval: 5s
  354. timeout: 5s
  355. retries: 5
  356. keeper:
  357. image: ghcr.io/ridafkih/keeper-services:2
  358. environment:
  359. DATABASE_URL: ${DATABASE_URL}
  360. REDIS_URL: ${REDIS_URL}
  361. BETTER_AUTH_URL: ${BETTER_AUTH_URL}
  362. BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
  363. ENCRYPTION_KEY: ${ENCRYPTION_KEY}
  364. GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
  365. GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
  366. MICROSOFT_CLIENT_ID: ${MICROSOFT_CLIENT_ID:-}
  367. MICROSOFT_CLIENT_SECRET: ${MICROSOFT_CLIENT_SECRET:-}
  368. ports:
  369. - "3000:3000"
  370. depends_on:
  371. postgres:
  372. condition: service_healthy
  373. redis:
  374. condition: service_healthy
  375. volumes:
  376. postgres-data:
  377. redis-data:
  378. ```
  379. Once that's configured, you can launch Keeper.sh using the following command.
  380. ```bash
  381. docker compose up -d
  382. ```
  383. ## Individual Service Images
  384. Running each service in its own image gives you the most control over scaling and placement, at the cost of a much longer configuration. Reach for this when `keeper-standalone` or `keeper-services` no longer fits, not before.
  385. ### Generate Individual Service Environment Variables
  386. ```bash
  387. cat > .env << EOF
  388. # The only optional variables are *_CLIENT_ID, *_CLIENT_SECRET
  389. BETTER_AUTH_SECRET=$(openssl rand -base64 32)
  390. ENCRYPTION_KEY=$(openssl rand -base64 32)
  391. VITE_API_URL=http://api:3001
  392. POSTGRES_USER=keeper
  393. POSTGRES_PASSWORD=keeper
  394. POSTGRES_DB=keeper
  395. REDIS_URL=redis://redis:6379
  396. BETTER_AUTH_URL=http://localhost:3000
  397. GOOGLE_CLIENT_ID=
  398. GOOGLE_CLIENT_SECRET=
  399. MICROSOFT_CLIENT_ID=
  400. MICROSOFT_CLIENT_SECRET=
  401. EOF
  402. ```
  403. ### Configure Individual Service `compose.yaml`
  404. ```yaml
  405. services:
  406. postgres:
  407. image: postgres:17
  408. command: ["postgres", "-c", "max_connections=200"]
  409. environment:
  410. POSTGRES_USER: ${POSTGRES_USER}
  411. POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  412. POSTGRES_DB: ${POSTGRES_DB}
  413. volumes:
  414. - postgres-data:/var/lib/postgresql/data
  415. healthcheck:
  416. test: ["CMD-SHELL", "pg_isready -U keeper -d keeper"]
  417. interval: 5s
  418. timeout: 5s
  419. retries: 5
  420. redis:
  421. image: redis:7-alpine
  422. volumes:
  423. - redis-data:/data
  424. healthcheck:
  425. test: ["CMD", "redis-cli", "ping"]
  426. interval: 5s
  427. timeout: 5s
  428. retries: 5
  429. api:
  430. image: ghcr.io/ridafkih/keeper-api:2
  431. environment:
  432. API_PORT: 3001
  433. DATABASE_URL: postgres://keeper:keeper@postgres:5432/keeper
  434. REDIS_URL: redis://redis:6379
  435. BETTER_AUTH_URL: ${BETTER_AUTH_URL}
  436. BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
  437. ENCRYPTION_KEY: ${ENCRYPTION_KEY}
  438. GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
  439. GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
  440. MICROSOFT_CLIENT_ID: ${MICROSOFT_CLIENT_ID:-}
  441. MICROSOFT_CLIENT_SECRET: ${MICROSOFT_CLIENT_SECRET:-}
  442. depends_on:
  443. postgres:
  444. condition: service_healthy
  445. redis:
  446. condition: service_healthy
  447. cron:
  448. image: ghcr.io/ridafkih/keeper-cron:2
  449. environment:
  450. DATABASE_URL: postgres://keeper:keeper@postgres:5432/keeper
  451. REDIS_URL: redis://redis:6379
  452. ENCRYPTION_KEY: ${ENCRYPTION_KEY}
  453. WORKER_JOB_QUEUE_ENABLED: "true"
  454. GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
  455. GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
  456. MICROSOFT_CLIENT_ID: ${MICROSOFT_CLIENT_ID:-}
  457. MICROSOFT_CLIENT_SECRET: ${MICROSOFT_CLIENT_SECRET:-}
  458. depends_on:
  459. postgres:
  460. condition: service_healthy
  461. redis:
  462. condition: service_healthy
  463. worker:
  464. image: ghcr.io/ridafkih/keeper-worker:2
  465. environment:
  466. DATABASE_URL: postgres://keeper:keeper@postgres:5432/keeper
  467. REDIS_URL: redis://redis:6379
  468. ENCRYPTION_KEY: ${ENCRYPTION_KEY}
  469. GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
  470. GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
  471. MICROSOFT_CLIENT_ID: ${MICROSOFT_CLIENT_ID:-}
  472. MICROSOFT_CLIENT_SECRET: ${MICROSOFT_CLIENT_SECRET:-}
  473. depends_on:
  474. postgres:
  475. condition: service_healthy
  476. redis:
  477. condition: service_healthy
  478. web:
  479. image: ghcr.io/ridafkih/keeper-web:2
  480. environment:
  481. VITE_API_URL: ${VITE_API_URL}
  482. PORT: 3000
  483. ports:
  484. - "3000:3000"
  485. depends_on:
  486. api:
  487. condition: service_started
  488. volumes:
  489. postgres-data:
  490. redis-data:
  491. ```
  492. Once that's configured, you can launch Keeper.sh using the following command.
  493. ```bash
  494. docker compose up -d
  495. ```
  496. # REST API
  497. Keeper.sh exposes a REST API under `/api/v1`. It is the same interface the dashboard and the MCP server use, so anything an agent can do through MCP you can do with `curl`.
  498. ## Authentication
  499. Create an API token from **Settings → API Tokens** in the dashboard. Tokens are prefixed with `kpr_` and the full value is only returned once, at creation time. Pass it as a bearer token.
  500. ```bash
  501. curl https://keeper.example.com/api/v1/calendars \
  502. -H "Authorization: Bearer kpr_..."
  503. ```
  504. `/api/v1` routes also accept a logged-in browser session or an MCP OAuth access token, so all three callers hit the same handlers. Token management itself lives at `/api/tokens` and requires a browser session rather than an API token.
  505. ## Endpoints
  506. | Method | Path | Description |
  507. | -------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  508. | `GET` | `/api/v1/calendars` | List connected calendars. Accepts an optional comma-delimited `provider` filter. |
  509. | `PATCH` | `/api/v1/calendars/{calendarId}` | Pause or resume syncing for a calendar. Send `paused` as `true` to halt it in both directions without disconnecting it. |
  510. | `GET` | `/api/v1/calendars/{calendarId}/invites` | List invitations on a calendar that have not been responded to, within a date range. |
  511. | `GET` | `/api/v1/accounts` | List connected calendar accounts and how many calendars each has. Accepts an optional comma-delimited `provider` filter. |
  512. | `GET` | `/api/v1/events` | List events in a date range. Accepts `calendarId`, `availability`, and `isAllDay` filters, a `timezone` whose local days all-day events fall on, and `count=true` to return only a count. |
  513. | `POST` | `/api/v1/events` | Create an event. Requires `calendarId`, `title`, `startTime`, and `endTime`. |
  514. | `GET` | `/api/v1/events/{id}` | Get a single event. |
  515. | `PATCH` | `/api/v1/events/{id}` | Update an event's fields, or send `rsvpStatus` to respond to an invitation. |
  516. | `DELETE` | `/api/v1/events/{id}` | Delete an event. |
  517. | `GET` | `/api/v1/events/free-time` | Find free slots of at least `durationMinutes` in a date range. Requires `timezone`, and accepts working-hours options. |
  518. | `POST` | `/api/v1/sync` | Trigger a sync immediately. Throttled to one request per minute per user. |
  519. | `GET` | `/api/v1/ical` | Get the URL of your iCal feed. |
  520. | `GET` | `/api/v1/mappings` | List which calendars sync into which, as source and destination calendar ID pairs. |
  521. | `PUT` | `/api/v1/calendars/{calendarId}/destinations` | Replace the calendars a calendar syncs to. Send `calendarIds`. |
  522. | `GET` | `/api/v1/calendars/{calendarId}/settings` | Get a calendar's sync settings and the calendars it syncs to and from. |
  523. | `PATCH` | `/api/v1/calendars/{calendarId}/settings` | Rename a calendar with `name`, or change its sync settings. Settings other than the name require Pro. |
  524. | `POST` | `/api/v1/accounts/{id}/refresh` | Re-discover the calendars on one connected account. |
  525. | `POST` | `/api/v1/accounts/refresh-calendars` | Re-discover the calendars on every connected account. Throttled to one request per minute per user. |
  526. | `POST` | `/api/v1/ics` | Subscribe to a calendar from its iCal link. Send `url`, and optionally `name`. |
  527. | `DELETE` | `/api/v1/ics/{calendarId}` | Remove a calendar added from an iCal link. |
  528. | `GET` | `/api/v1/ical/feeds` | List your iCal feeds with their URLs, settings and calendar IDs. |
  529. | `POST` | `/api/v1/ical/feeds` | Create an iCal feed. Send `name`. |
  530. | `PATCH` | `/api/v1/ical/feeds/{id}` | Rename an iCal feed or change its settings. Settings other than the name require Pro. |
  531. | `PUT` | `/api/v1/ical/feeds/{id}/calendars` | Replace the calendars an iCal feed publishes. Send `calendarIds`. |
  532. | `DELETE` | `/api/v1/ical/feeds/{id}` | Delete an iCal feed. The default feed cannot be deleted. |
  533. | `POST` | `/api/v1/agent-feedback` | Intake for `send_feedback`. Takes no token and is called by MCP servers, not users. On Keeper.sh it stores the feedback and notifies the team. |
  534. Range parameters `from` and `to` are ISO 8601 datetimes. If omitted, `from` defaults to now and `to` defaults to a week after `from`. A range may not exceed 732 days.
  535. On `POST` and `PATCH /api/v1/events`, a `startTime` or `endTime` without a UTC offset is read in `timezone`, which is then required; times with `Z` or an offset are used as given, and all-day events take the calendar date as written.
  536. `/api/v1/events/free-time` treats events marked free or working-elsewhere as non-blocking and everything else, including all-day events, as busy; pass `ignoreAllDayEvents=true` to stop all-day events blocking. `workingHoursStart` and `workingHoursEnd` are 24-hour local times such as `09:00`, and `workingDays` is a comma-delimited list where `0` is Sunday. All three are read against `timezone`, so the hours hold across daylight saving transitions.
  537. `POST /api/v1/sync` clears the ingest backoff on your sources so they are re-polled on the next pass, and enqueues a push to every destination. Exceeding the throttle returns `429` with a `Retry-After` header rather than queueing a second run.
  538. > [!NOTE]
  539. >
  540. > On the free plan the API is capped at 25 requests per day, after which requests return `429`. Pro is uncapped, and self-hosted instances running without `COMMERCIAL_MODE` are treated as Pro.
  541. # MCP (Model Context Protocol)
  542. Keeper.sh includes an optional MCP server that lets AI agents (such as Claude) access your calendar data through a standardized protocol. The MCP server authenticates via OAuth 2.1 with a consent flow hosted by the web application.
  543. ## Available Tools
  544. | Tool | Description |
  545. | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
  546. | `list_calendars` | List all calendars connected to Keeper.sh, including provider name and account. |
  547. | `get_event_count` | Get the number of calendar events. Optionally scoped to a date range with `from` and `to` ISO 8601 datetimes, and an IANA timezone whose local days all-day events count on. |
  548. | `get_events` | Get calendar events within a date range. Accepts ISO 8601 datetimes and an IANA timezone identifier used to localize event times. All-day events return `YYYY-MM-DD` dates with an exclusive end. |
  549. | `get_event` | Get a single calendar event by its ID. |
  550. | `find_free_time` | Find open slots of at least a given duration across every synced calendar in a date range. |
  551. | `create_event` | Create an event on a connected calendar. Requires a calendar ID, title, start time, and end time. |
  552. | `update_event` | Update an existing calendar event. Only the fields you provide are updated. |
  553. | `delete_event` | Delete a calendar event by its ID. |
  554. | `get_pending_invites` | Get invitations on a calendar that have not been responded to within a date range. |
  555. | `rsvp_event` | Respond to a calendar event invitation with `accepted`, `declined`, or `tentative`. |
  556. | `list_accounts` | List all connected calendar accounts with provider information. |
  557. | `trigger_sync` | Force a sync now instead of waiting for the next scheduled run. Throttled to one request per minute. |
  558. | `pause_sync` | Pause or resume syncing for a single calendar without disconnecting it. |
  559. | `list_syncs` | List which calendars sync into which. |
  560. | `set_sync_destinations` | Set the calendars a calendar syncs to, replacing its current destinations. |
  561. | `get_calendar_settings` | Get a calendar's sync settings. |
  562. | `update_calendar_settings` | Change how a calendar's events are copied: the copy title, excluded events and details, privacy, reminders and the sync window. Requires Pro. |
  563. | `rename_calendar` | Rename a calendar in Keeper.sh. |
  564. | `refresh_calendars` | Re-discover the calendars on one connected account, or on every account. |
  565. | `add_calendar_link` | Subscribe to a read-only calendar from its iCal link. |
  566. | `remove_calendar_link` | Remove a calendar added from an iCal link. |
  567. | `list_ical_feeds` | List your iCal feeds with their subscription URLs, settings and calendars. |
  568. | `create_ical_feed` | Create an iCal feed. |
  569. | `update_ical_feed` | Rename an iCal feed or change what its events show. |
  570. | `set_ical_feed_calendars` | Set which calendars an iCal feed publishes. |
  571. | `delete_ical_feed` | Delete an iCal feed. |
  572. | `send_feedback` | Send the Keeper.sh team feedback about the MCP tools and API: an unexpected error, a confusing result, a missing capability, unclear docs or a workaround. |
  573. Every tool also accepts an optional `intent`, up to 300 characters, where an agent can say what it is trying to do. Unless the user has turned agent feedback off, it is recorded with the tool name on the request's log event, is never sent to the API or echoed back, and has no effect on what the tool does.
  574. ## Agent Feedback
  575. `send_feedback` takes a `message` (the goal, what was tried and where it got stuck, up to 2,000 characters), a `category` (`tool_error`, `missing_capability`, `confusing_output`, `documentation` or `other`), an optional `toolName` and an optional `severity` (`high` when blocked, `medium` when a workaround was found, `low` for an annoyance; defaults to `medium`).
  576. Feedback always goes to the Keeper.sh team at `https://www.keeper.sh/api/v1/agent-feedback`, including from self-hosted instances, so problems with the tools reach the people who maintain them. It carries only the message, category, severity, tool name, the intent given on that call, the instance's Keeper.sh version, and whether the instance is hosted or self-hosted. It never carries the user's token, ID, email, calendar data or the instance's hostname.
  577. Each user can turn this off with **Agent feedback** in **Settings**, stored per account and served at `GET` and `PATCH /api/account/settings`. With it off, `send_feedback` is left out of that user's tool list and a call to it sends nothing, the server's instructions and error messages stop mentioning it, and `intent` is still accepted but not recorded. Operators can turn it off for the whole instance with `AGENT_FEEDBACK_DISABLED`.
  578. ## Connecting an MCP Client
  579. To connect an MCP-compatible client (e.g. Claude Code, Claude Desktop), point it at your MCP server URL. The client will be guided through the OAuth consent flow to authorize read and write access to your calendar data — the toolset can create, update, delete, and RSVP to events, find open time, pause or force a sync, change which calendars sync where and how, and manage calendar links and iCal feeds, not just read them.
  580. Example Claude Code MCP configuration:
  581. ```json
  582. {
  583. "mcpServers": {
  584. "keeper": {
  585. "type": "url",
  586. "url": "https://keeper.example.com/mcp"
  587. }
  588. }
  589. }
  590. ```
  591. ## Self-Hosted MCP Setup
  592. > [!NOTE]
  593. >
  594. > MCP is fully optional. All MCP-related environment variables are optional across every service and image. If they are not set, Keeper.sh starts normally without MCP functionality. Existing self-hosted deployments are unaffected.
  595. The MCP server is proxied through the web service at `/mcp`, the same way the API is proxied at `/api`.
  596. `keeper-standalone` bundles the MCP server and serves it at `/mcp` on the port you already publish, with no extra configuration. It derives `MCP_PUBLIC_URL` from `BETTER_AUTH_URL`, so as long as `BETTER_AUTH_URL` is your instance URL, your MCP client points at that same URL with `/mcp` appended.
  597. MCP is **not** bundled in `keeper-services` or the individual service images. To enable it there:
  598. 1. Run the `keeper-mcp` container with `MCP_PORT`, `MCP_PUBLIC_URL`, `DATABASE_URL`, `BETTER_AUTH_SECRET`, and `BETTER_AUTH_URL`.
  599. 2. Set `MCP_PUBLIC_URL` on the `api` service to the same value (e.g. `https://keeper.example.com/mcp`).
  600. 3. Set `VITE_MCP_URL` on the `web` service to the internal URL of the MCP container (e.g. `http://mcp:3002`).
  601. ## Registry Manifest
  602. [`server.json`](./server.json) at the repository root describes the hosted server for the [official MCP Registry](https://registry.modelcontextprotocol.io). It carries a single `streamable-http` remote pointing at `https://www.keeper.sh/mcp`, and is listed as `io.github.ridafkih/keeper-sh`, the name it was first published under; a registry name cannot be changed once published. The server announces the same name, version, title, website and icons in its `initialize` response.
  603. Publishing is a manual step run with the `mcp-publisher` CLI and is deliberately not automated: a published version is permanent, so the manifest is reviewed here first and the `version` it carries can never be reused. Self-hosted instances do not need this file — it describes the hosted instance only.
  604. Because the entry is permanent, publish only after every URL it names resolves in production — `websiteUrl`, both `icons[].src`, and the `streamable-http` remote. A `websiteUrl` pointing at a page that has not shipped yet is stuck at a 404 until the next version bump.
  605. # Modules
  606. ## Applications
  607. 1. [@keeper.sh/web](./applications/web)
  608. ## Services
  609. 1. [@keeper.sh/api](./services/api)
  610. 2. [@keeper.sh/cron](./services/cron)
  611. 3. [@keeper.sh/mcp](./services/mcp)
  612. 4. [@keeper.sh/worker](./services/worker)
  613. ## Modules
  614. 1. [@keeper.sh/auth](./packages/auth)
  615. 1. [@keeper.sh/broadcast](./packages/broadcast)
  616. 1. [@keeper.sh/calendar](./packages/calendar)
  617. 1. [@keeper.sh/constants](./packages/constants)
  618. 1. [@keeper.sh/data-schemas](./packages/data-schemas)
  619. 1. [@keeper.sh/database](./packages/database)
  620. 1. [@keeper.sh/digest-fetch](./packages/digest-fetch)
  621. 1. [@keeper.sh/fixtures](./packages/fixtures)
  622. 1. [@keeper.sh/otelemetry](./packages/otelemetry)
  623. 1. [@keeper.sh/premium](./packages/premium)
  624. 1. [@keeper.sh/queue](./packages/queue)
  625. 1. [@keeper.sh/sync](./packages/sync)
  626. 1. [@keeper.sh/typescript-config](./packages/typescript-config)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.