keeper.sh MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

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)

라이브 데모

실제 사용 모습

keeper-sh.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/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
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

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

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

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

context_servers에 추가. 저장 시 Zed가 핫 리로드.

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

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: keeper.sh

How to get a daily schedule briefing from all your calendars

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

언제 쓸까: Every morning when you want Claude to summarize your day across Google, Outlook, and iCloud calendars in one shot.

사전 조건

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

흐름

List connected calendars

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

→ 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.✓ 복사됨

→ 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.✓ 복사됨

→ Time-blocked suggestions fitting around existing events

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

함정

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

함께 쓰기: notion · linear

Analyze your meeting load to reclaim focus time

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

언제 쓸까: End of week when you suspect meetings ate all your deep work time.

흐름

Pull this week's event count

How many calendar events did I have this week? Break down by calendar.✓ 복사됨

→ 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.✓ 복사됨

→ Hour totals and gap analysis
Suggest improvements

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

→ Specific meetings to cancel or move

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

함정

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

언제 쓸까: Before scheduling something new, check all calendars for conflicts.

흐름

Query a time range

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

→ 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.✓ 복사됨

→ Concrete time slots with no conflicts

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

함정

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

조합

다른 MCP와 조합해 10배 효율

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.✓ 복사됨

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.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
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

비용 및 제한

운영 비용

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

보안

권한, 시크릿, 파급범위

최소 스코프: calendar:read (per connected provider)

자격 증명 저장: OAuth tokens and CalDAV credentials encrypted at rest. Session signing via BETTER_AUTH_SECRET env var.

데이터 외부 송신: Self-hosted: stays on your server. Cloud: keeper.sh servers. Calendar API calls go to Google/Microsoft/iCloud respectively.

절대 부여 금지: 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.

문제 해결

자주 발생하는 오류와 해결

CSRF validation failed

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

확인: 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.

확인: 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.

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

대안

keeper.sh 다른 것과 비교

대안	언제 쓰나	단점/장점
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

keeper.sh