MCP Server & REST API

What the server does

Keeper.sh syncs events between Google Calendar, Outlook, iCloud, Fastmail, CalDAV servers, and iCal links. The MCP server puts that same merged view in front of an assistant: one connection reads and writes every calendar you have connected, rather than one integration per provider.

It speaks the Model Context Protocol over streamable HTTP at https://www.keeper.sh/mcp, and every tool is a thin wrapper over the public REST API described further down. Writes go through to the provider that owns the calendar, so an event an assistant creates appears in Google Calendar or Outlook exactly like one you made by hand, and Keeper.sh keeps syncing it from there.

Self-hosted instances serve the same endpoint at /mcp on your own domain. Everything on this page applies to them, with your instance URL in place of www.keeper.sh.

Quickstart

You need a Keeper.sh account with at least one calendar connected. There is no key to copy: the client registers itself and you approve it in the browser.

1. Point an MCP client at https://www.keeper.sh/mcp.
2. The first request comes back 401 with a WWW-Authenticate header, and the client follows it into the OAuth flow.
3. Sign in and approve the consent screen. The client stores the tokens it gets back.
4. Ask it something like “what is on my calendar tomorrow?”. It should call get_events.

Configuration for a client that takes a JSON server list:

{
  "mcpServers": {
    "keeper": {
      "type": "url",
      "url": "https://www.keeper.sh/mcp"
    }
  }
}

Authentication with OAuth 2.1

The MCP server is an OAuth 2.1 protected resource. It never sees your password, and there is nothing to paste into a client.

An unauthenticated request is answered 401 with WWW-Authenticate: Bearer resource_metadata=…, which points at the protected resource metadata document. That document names the authorization server, and the client discovers the rest from there.

curl https://www.keeper.sh/.well-known/oauth-protected-resource

{
  "resource": "https://www.keeper.sh/mcp",
  "authorization_servers": ["https://www.keeper.sh/api/auth"],
  "scopes_supported": ["keeper.read", "keeper.events.read", "..."]
}

Clients register themselves through dynamic client registration, so you do not create an OAuth app first. Authorization uses the authorization code flow with PKCE, and the consent screen is hosted by Keeper.sh at /oauth/consent. Access tokens last 30 days and refresh tokens 90 days; a client that asks for offline_access can refresh without sending you back through consent.

Every tool call requires the keeper.read scope. A token without it is answered 403 with error="insufficient_scope". The scopes a client may request are:

Write tools are covered by the same grant: the token is passed straight through to the REST API, which authorizes it as your account. Revoking access in the dashboard cuts the client off from both.

Tools

The server exposes 14 tools. Date ranges are ISO 8601 datetimes, and read tools that take a timezone return times already localized to it, so an assistant does not have to convert anything itself.

Worked examples

What a session actually looks like. The prompts are yours; the calls are what the assistant makes.

get_events(from: "2026-09-10T00:00:00Z", to: "2026-09-11T00:00:00Z", timezone: "America/New_York")

find_free_time(from: …, to: …, timezone: "America/New_York", durationMinutes: 45, workingHoursStart: "09:00", workingHoursEnd: "17:00", workingDays: "1,2,3,4,5")
list_calendars()
create_event(calendarId: …, title: "Design review", startTime: …, endTime: …, timezone: "America/New_York")

get_pending_invites(calendarId: …, from: …, to: …, timezone: "America/New_York")
rsvp_event(eventId: …, rsvpStatus: "declined")

REST API

The MCP tools call the same public API you can call yourself, under /api/v1. Anything an assistant can do through MCP you can do with curl.

Create a token from Settings → API Tokens in the dashboard. Tokens are prefixed with kpr_ and shown once, at creation. Pass one as a bearer token. The same routes also accept a logged-in browser session or an MCP OAuth access token, so all three callers reach the same handlers.

curl https://www.keeper.sh/api/v1/calendars \
  -H "Authorization: Bearer kpr_..."

Range parameters from and to are ISO 8601 datetimes. If omitted, from defaults to now and to to a week later. A range may not exceed 732 days.

Finding free time

Events marked free or working-elsewhere are treated as non-blocking; everything else, including all-day events, is busy. Pass ignoreAllDayEvents=true to stop all-day events blocking. Working hours are 24-hour local times and workingDays counts 0 as Sunday, both read against timezone, so the hours hold across daylight saving transitions.

curl -G https://www.keeper.sh/api/v1/events/free-time \
  -H "Authorization: Bearer kpr_..." \
  --data-urlencode "from=2026-09-07T00:00:00Z" \
  --data-urlencode "to=2026-09-11T00:00:00Z" \
  --data-urlencode "timezone=America/New_York" \
  --data-urlencode "durationMinutes=45" \
  --data-urlencode "workingHoursStart=09:00" \
  --data-urlencode "workingHoursEnd=17:00" \
  --data-urlencode "workingDays=1,2,3,4,5"

Creating an event

The calendar ID comes from GET /api/v1/calendars. Sending a timezone keeps CalDAV providers such as iCloud and Fastmail from rendering the event in GMT.

curl -X POST https://www.keeper.sh/api/v1/events \
  -H "Authorization: Bearer kpr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId": "6f1c0c2e-1f5f-4a2f-9a1e-6a1b7f0c9d3e",
    "title": "Design review",
    "startTime": "2026-09-08T15:00:00Z",
    "endTime": "2026-09-08T15:45:00Z",
    "timezone": "America/New_York"
  }'

Limits

On the free plan the API and MCP server together are 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. POST /api/v1/sync and trigger_sync are separately throttled to one request per minute per user, and answer 429 with a Retry-After header rather than queueing a second run.