keeper.sh MCP — Use Cases, Install & Live Demo

Why use it

Key features

Aggregates 6+ calendar providers into one unified event stream
MCP server with list_calendars, get_events, and get_event_count tools
Self-hostable via Docker (standalone, services, or granular)
OAuth 2.0 for Google and Microsoft; CalDAV credentials encrypted at rest
Free tier (30-min refresh, 2 sources) and Pro tier ($5/mo, 1-min sync, unlimited)

Live Demo

What it looks like in practice

keeper-sh.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "keeper-sh": {
      "command": "npx",
      "args": [
        "-y",
        "keeper.sh"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "keeper-sh": {
      "command": "npx",
      "args": [
        "-y",
        "keeper.sh"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "keeper-sh": {
      "command": "npx",
      "args": [
        "-y",
        "keeper.sh"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "keeper-sh": {
      "command": "npx",
      "args": [
        "-y",
        "keeper.sh"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "keeper-sh",
      "command": "npx",
      "args": [
        "-y",
        "keeper.sh"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "keeper-sh": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "keeper.sh"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add keeper-sh -- npx -y keeper.sh

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use keeper.sh

How to get a daily schedule briefing from all your calendars

👤 Professionals juggling work + personal calendars across providers ⏱ ~5 min beginner

When to use: Every morning when you want Claude to summarize your day across Google, Outlook, and iCloud calendars in one shot.

Prerequisites

keeper.sh running with calendars connected — npx -y keeper.sh or self-host via Docker; connect providers in the web UI

Flow

List connected calendars

List all my connected calendars in keeper.sh — show provider and account for each.✓ Copied

→ Table of calendars with provider names
Pull today's events

Get all events from today across all calendars. Group by morning/afternoon/evening and flag any conflicts.✓ Copied

→ Chronological event list with conflict warnings
Plan the day

Given those events, suggest an optimal order for my 3 unscheduled tasks: code review, doc writing, and 1:1 prep.✓ Copied

→ Time-blocked suggestions fitting around existing events

Outcome: A single-view daily briefing across all calendar providers with actionable scheduling advice.

Pitfalls

Stale events on the free tier (30-min refresh) — Trigger a manual sync in the web UI before querying, or upgrade to Pro for 1-min refresh

Combine with: notion · linear

Analyze your meeting load to reclaim focus time

👤 Engineering managers and ICs drowning in meetings ⏱ ~10 min beginner

When to use: End of week when you suspect meetings ate all your deep work time.

Flow

Pull this week's event count

How many calendar events did I have this week? Break down by calendar.✓ Copied

→ Count per calendar
Get event details for the week

Get all events from Monday through Friday this week. Calculate total meeting hours and longest uninterrupted block.✓ Copied

→ Hour totals and gap analysis
Suggest improvements

Which recurring meetings could be async? Flag any that overlap or back-to-back with no break.✓ Copied

→ Specific meetings to cancel or move

Outcome: A data-driven view of your meeting load with concrete suggestions to reclaim time.

Pitfalls

All-day events inflate meeting hours — Ask Claude to filter out all-day events before calculating

Detect scheduling conflicts across work and personal calendars

👤 Anyone with calendars on different providers that don't talk to each other ⏱ ~5 min beginner

When to use: Before scheduling something new, check all calendars for conflicts.

Flow

Query a time range

Get all events next Tuesday between 9am and 5pm across all calendars. Are there any overlaps?✓ Copied

→ List of events with any conflicts highlighted
Find open slots

Find 3 open 1-hour slots next week that are free across all my calendars.✓ Copied

→ Concrete time slots with no conflicts

Outcome: Conflict-free scheduling across providers without manually checking each calendar.

Pitfalls

Timezone mismatches between providers — Always specify IANA timezone in your prompt (e.g., 'in America/New_York')

Combinations

Pair with other MCPs for X10 leverage

keeper-sh + notion

Pull today's calendar events and create a Notion daily planner page with time blocks

Get today's events from keeper.sh, then create a Notion page in my Daily Notes database with time-blocked tasks around the meetings.✓ Copied

keeper-sh + linear

Check calendar availability before assigning sprint tasks with deadlines

Show my free blocks this week via keeper.sh, then assign these 3 Linear issues to slots where I have 2+ hours free.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_calendars	none	See all connected calendars and their providers	1 local API call
get_events	start: ISO 8601, end: ISO 8601, timezone: IANA	Retrieve events within a date range	1 local API call
get_event_count	none	Quick check of total synced events	1 local API call

Cost & Limits

What this costs to run

API quota: Self-hosted: unlimited. Cloud free tier: 30-min refresh, 2 sources, 1 destination.
Tokens per call: 100-500 tokens per tool call; large date ranges can return more
Monetary: Self-hosted: free (AGPL). Cloud: free tier or $5/month Pro (1-min sync, unlimited sources).
Tip: Self-host the standalone Docker image for zero recurring cost. Cloud Pro is worth it only if you need sub-minute sync.

Security

Permissions, secrets, blast radius

Minimum scopes: calendar:read (per connected provider)

Credential storage: OAuth tokens and CalDAV credentials encrypted at rest. Session signing via BETTER_AUTH_SECRET env var.

Data egress: Self-hosted: stays on your server. Cloud: keeper.sh servers. Calendar API calls go to Google/Microsoft/iCloud respectively.

Never grant: calendar:write (unless you explicitly need sync destinations)

Set TRUSTED_ORIGINS if accessing from a non-localhost domain to prevent CSRF.
Set BLOCK_PRIVATE_RESOLUTION=true in production to prevent SSRF via CalDAV URLs.

Troubleshooting

Common errors and fixes

CSRF validation failed

Set the TRUSTED_ORIGINS environment variable to your domain (e.g., https://calendar.example.com)

Verify: Check the keeper.sh web UI loads without 403 errors

Google OAuth redirect fails

Ensure your Google Cloud OAuth consent screen has the correct redirect URI matching your keeper.sh deployment URL

Events not refreshing

Free tier refreshes every 30 minutes. Trigger a manual sync in the web UI, or upgrade to Pro for 1-minute sync.

Verify: Check get_event_count before and after manual sync

CalDAV connection rejected

Verify the CalDAV URL includes the full path (usually /dav/calendars/user/). Check credentials and ensure the server supports CalDAV, not just CardDAV.

Verify: curl -u user:pass -X PROPFIND <caldav-url>

Alternatives

keeper.sh vs others

Alternative	When to use it instead	Tradeoff
Google Calendar MCP	You only use Google Calendar and want a simpler setup	Single provider; no aggregation across Outlook/iCloud
Notion Calendar	You're already deep in the Notion ecosystem	Proprietary; no MCP interface

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills