For developers: tool reference
The Kalender Sync MCP server (https://app.kalender-sync.de/mcp, Streamable HTTP) exposes up to 22 tools.
Connected calendar and sync tools follow these rules. Subscribe calendars have a separate permission, described below:
- Visibility gating: each tool only sees the calendars you shared, and per calendar only the allowed detail level. Calendars you did not share do not exist for the server.
- Dynamic tool list: the four write tools only appear when your access may write;
create_sync,set_sync_paused,preview_delete_syncanddelete_synconly when at least one calendar is released for syncs (granted per calendar). Without Publisher permission, an access with default sync scope and no write permission sees 7 tools (4 base tools and 3 reading sync tools) — we don’t ship tools that would always refuse. If you change write permissions later, the tools only show up once the client reloads the tool list.
Credits and result status
Section titled “Credits and result status”list_calendars, send_feedback and all sync and subscribe-calendar tools cost 0 credits and work with an empty balance. search_events costs 1 credit; get_availability and each event write call (create, update, delete, respond) cost 2 credits. Only successfully executed, chargeable calls are billed.
The six chargeable tools return status: "ok" alongside their result fields when executed. When there are insufficient credits, they instead return status: "credits_exhausted", warnings, credits_available, credits_required, and resets_at (an ISO timestamp or null). This is a regular tool result without isError, but no calendar action was performed: busy, matches, event_id, and all write confirmations are absent. Actual errors remain errors.
Always check status first. A credit denial means neither “no events” nor “event created/updated/deleted”. Show the warning and do not retry automatically. After a confirmed upgrade or top-up, retrying is appropriate. Free users can upgrade; extra credits can be purchased on Basic and above. The denial remains visible in the access log as denied_credits.
Clients with cached tool schemas must reload the tool list for version 1.6.0, for example by reconnecting; only then do the sync tools appear. Result fields are optional in the schema because they are absent on a credit denial; with status: "ok", the tool’s usual result fields still apply.
Read tools
Section titled “Read tools”list_calendars
Section titled “list_calendars”Lists the shared calendars with their detail level. readable: false marks calendars that can’t be read right now (they are then missing from every other answer too — and are deliberately listed rather than omitted). writable: true marks the calendars this access may create events in — that is where the calendar_id for create_event comes from. sync_health additionally shows the state of Kalender Sync’s own synchronisation of that calendar, if it takes part in one.
notice, when present, explains a write-access limitation and how to resolve it. It is relevant when the requested action needs that access.
missing_calendars (since 1.8.0, always present) says what to do when an expected calendar is missing. If there are calendars created after connecting that this access doesn’t see yet, the field gives their count, never their names, and how to share them.
Parameters: none.
get_availability
Section titled “get_availability”Returns the events in a range, across all shared calendars. Every calendar is read directly at the provider (no copy); reads are reused for up to 60 seconds. After this assistant successfully creates, changes or deletes an event, or answers an invitation, the affected calendar is read again on the next request. Everything is included except cancelled events — all-day events and “tentative” ones too. If a calendar could not be read, that appears in sources and warnings — an answer never claims a completeness it doesn’t have.
Per entry, blocks_time says whether it actually occupies the time. It is false for entries that don’t make you unavailable: holidays, birthdays, and every all-day event from Apple/iCloud, which that provider always marks as free with no setting for you to change. Such an entry is still a real appointment — an all-day “Baustelle Darmstadt” is a working day, not free time. So for “am I free?” only blocks_time: true counts, while “what do I have on?” counts everything.
| Parameter | Required | Description |
|---|---|---|
from / to | yes | Range, ISO 8601. Max span 92 days, lookback bounded to 365 days. |
search_events
Section titled “search_events”Finds events by text — case-insensitive substring over title, location and description. The search is deliberately a filter over the same visibility-rendered data get_availability returns, not a second read path: calendars on the “busy only” level carry no titles and therefore can never match — the answer says so as a warning. “No match” is never proof that the event doesn’t exist.
| Parameter | Required | Description |
|---|---|---|
query | yes | Search text (min. 2 characters) |
from / to | no | Range as in get_availability; default −7 to +85 days |
At most 50 matches (the chronologically earliest), truncated signals when the cap was hit.
send_feedback
Section titled “send_feedback”The notification to the team cannot be recalled once sent. The tool therefore declares destructiveHint: true, even though it does not change calendar events.
Sends the user’s feedback to the Kalender Sync team — for example when they wanted something the tools can’t do yet. The assistant is instructed to use this only on the user’s explicit request. contact_ok (default: off, including bug reports) permits exactly one topical reply from us — no newsletter, no mailing list. Processing details in the privacy policy, section 3.10.
| Parameter | Required | Description |
|---|---|---|
message | yes | The feedback (10–2000 characters) |
category | yes | missing_capability · bug · other |
contact_ok | no | Only if the user explicitly agreed to a single reply |
Write tools (all plans, granted per calendar)
Section titled “Write tools (all plans, granted per calendar)”Separate permissions per calendar: create events and, below it, change and delete existing events and manage syncs into this calendar (see sync tools). Without the second, the assistant can only touch what it created itself — your existing events are then technically not addressable. When connecting, the sliders icon next to the access label opens these permissions; newly selected calendars start with maximum supported permissions, which can be narrowed before sharing. More under write access.
create_event
Section titled “create_event”Creates an event in a writable calendar. Availability is checked live at write time (not from cache): an overlap does not prevent creation but comes back as a warning — whether to double-book is the user’s call. Only entries that actually occupy the time are counted (blocks_time: true). Holidays, birthdays and all-day events from Apple/iCloud deliberately raise no warning, since otherwise every booking on a holiday would look like a clash. So no warning does not mean the day is empty. start/end require ISO 8601 with a timezone; calendar_id is only needed with several writable calendars — list_calendars shows which those are via writable: true. If it is omitted with several, the error message names the permitted calendars.
update_event · delete_event
Section titled “update_event · delete_event”Update or delete an event. Two kinds are addressable:
- Events this access created itself (via the
event_idfromcreate_event) — always. - Existing events in a calendar you granted “change and delete” for — via the
event_idfromget_availabilityorsearch_events.
The second kind has four conditions, and every refusal names the way forward: the calendar is granted, shared at All details, the event is not a synchronised copy (otherwise the next sync overwrites the change — the refusal names the source calendar), and you are the organiser. Someone else’s invitation cannot be rewritten; respond_to_event handles those. The one exception is your own reminders.
Only what the call names changes — reminders (unless reminders is given), attendees and repeat rules stay, on CalDAV too. The event_id of a single date of a series changes or deletes only that date. If the event has attendees, the provider notifies them of the change or cancellation.
Events that are not addressable answer not_found, not forbidden — so existence is not even confirmed. Deletions are executed at the provider and propagate into mirrored calendars through the normal sync. Both tools carry the MCP annotation destructiveHint: true.
Reminders (reminders)
Section titled “Reminders (reminders)”create_event and update_event set pop-up reminders: reminders: [{ "minutes_before": 1440 }, { "minutes_before": 60 }] means one day and one hour before. Most important first, at most five, each 0 to 40320 minutes (four weeks). For all-day events the minutes count back from 00:00 of the day: 900 is 9am the day before.
- Leaving it out keeps the reminders as they are; on create, the calendar’s default reminder applies.
[]removes them all. A list replaces the previous ones entirely. - Changing only the reminders:
update_eventwithevent_id,calendar_idandreminders, withouttitle,startandend. This also works on invitations from others — the reminders are yours, and the organiser is not told. Title and time of an invitation stay locked. - What was actually stored: after every write the server reads the reminders back from the provider. The answer lists
reminders(stored) andreminders_not_keptwith a warning the assistant passes on. A provider’s “OK” alone proves nothing: Google silently caps long lead times, Outlook keeps only one. - Reading: in calendars with “change and delete” at All details,
get_availabilityandsearch_eventsreturn your reminders next to theevent_id.source: "calendar_default"means the event follows the Google calendar’s default reminder.
| Provider | Reminders per event | Note |
|---|---|---|
| 5 | Yours only, also in shared calendars and on invitations | |
| Outlook / Microsoft 365 | 1 | Only the first of the list is stored; the answer reports the rest as not kept |
| iCloud | 5 | Arrives as a notification on the iPhone; yours only |
| GMX, WEB.DE | 5 | |
| KSuite, mailbox.org, Posteo, STRATO | 5 | |
| Disroot | 5 | Nextcloud: in a shared calendar the reminder applies to everyone who can edit it |
| iCal feeds | — | Read-only |
Pop-up reminders only; the assistant does not set e-mail reminders. Synchronised copies never carry your reminders.
respond_to_event
Section titled “respond_to_event”Answers someone else’s invitation: accept, decline or tentatively accept. The organiser is notified — that is the point: merely deleting an invitation removes it locally and leaves them expecting you.
The permission is the same one as for changing, but the condition is the inverse: changing requires you to be the organiser, answering requires you not to be. For a recurring appointment scope is needed — occurrence answers that date only, series answers all of them. Without it the assistant asks rather than guesses: a decline sent to the organiser cannot be taken back.
Available for Google, Microsoft and CalDAV servers with scheduling (RFC 6638 — e.g. KSuite, WEB.DE). iCloud only delivers answers to organisers who use iCloud themselves; invitations from outside (Google, Outlook) iCloud does not put into the calendar on its own. On CalDAV the server delivers the answer; where it cannot, the tool returns not_supported and points at the calendar app instead of sending an answer nobody receives. A comment does not travel over CalDAV; the answer still goes out, and warnings says so.
Sync tools
Section titled “Sync tools”Seven tools for your syncs, all 0 credits. They require the OAuth scope sync.manage, which every access has by default. create_sync, set_sync_paused, preview_delete_sync and delete_sync additionally only appear when at least one calendar has the “manage syncs into this calendar” tick; list_calendars reports such calendars with sync_target: true.
Calendars outside your selection appear with id: null and name: null — the sync itself is not hidden. If a call names a calendar that is not shared, belongs to someone else or does not exist, the answer is the same in all three cases.
list_syncs
Section titled “list_syncs”Lists your own syncs: sources, target, kind (own_calendars or shared_with_person — for the latter the other person’s calendar is never named), two_way, status (active · paused · error), reason, next_step and next_step_url. A two-way sync is one entry. Open invitations and ended syncs are left out. Since 1.9.1 every entry has event_colors: off, source (copies keep their colors), fixed (one color per source calendar) or mixed (the two directions of a two-way sync differ).
reason is a closed list: user_paused, plan_limit, source_unavailable, target_unavailable, account_needs_reconnect, updating, sync_error, other. Provider error texts are never passed on. ref (sync_1, sync_2, …) is the input for diagnose_sync and set_sync_paused; it is positional (oldest first) and only valid for the current result.
Parameters: none.
diagnose_sync
Section titled “diagnose_sync”The same entry for one sync, plus explanation (one fixed sentence per reason), last_synced_at and error_since. For other and sync_error no next step is claimed.
| Parameter | Required | Description |
|---|---|---|
ref | yes | ref from a current list_syncs result |
preview_sync
Section titled “preview_sync”Checks whether a sync could be created — one way or both ways — without creating anything. Returns can_create, all blockers at once, max_detail_level (the highest detail level this access sees of the source) and, for two-way, max_reverse_detail_level for the way back. It deliberately states no number of copies (effect: "ongoing_copy_unknown_volume"). A positive preview is not a reservation.
Possible blockers: same_calendar, already_connected, reverse_sync_exists, would_create_cycle, target_read_only, account_needs_reconnect, detail_level_above_access, plan_sync_limit_reached, plan_excludes_own_calendar_sync, plan_excludes_event_colors (since 1.9.0, only when event_colors: true is asked for explicitly).
| Parameter | Required | Description |
|---|---|---|
source_calendar_id | yes | Source calendar, must be shared |
target_calendar_id | yes | Target calendar, must be released for syncs (sync_target: true in list_calendars) |
detail_level | no | busy_only · title_and_time · full_details; also checked against max_detail_level |
direction | no | one_way (default) · two_way; for two-way both calendars must be shared and sync targets |
reverse_detail_level | no | Two-way only: detail level of the way back, default = detail_level |
event_colors | no | Since 1.9.0: checks whether the plan allows event colors |
create_sync
Section titled “create_sync”Creates a sync between two of your own calendars — one way or as a two-way sync — after you confirmed source, target, direction and detail level(s) in the chat. For two-way, both directions are created together or not at all (legs: 2). All preview checks run again. Response: status: "created_pending_processing" — the sync exists, copying happens in the background, and the target calendar may look empty for a few minutes. syncs_url links to the app. The sync keeps running after the access is revoked.
Idempotent via request_id: the same id with the same input returns the same sync (replayed: true), the same id with different input fails. Annotation: destructiveHint: true.
Event colors (event_colors, since 1.9.0): colors travel with their names (Google labels, Outlook categories). Renames and, where Microsoft asks for it, the permission to create categories are set in the app (syncs_url). Without that permission the sync runs in the calendar color.
| Parameter | Required | Description |
|---|---|---|
source_calendar_id | yes | Source calendar |
target_calendar_id | yes | Target calendar |
detail_level | yes | busy_only · title_and_time · full_details, at most max_detail_level |
request_id | yes | Stable id (8–100 characters), the same on retries |
direction | no | one_way (default) · two_way |
reverse_detail_level | no | Two-way only, at most max_reverse_detail_level |
event_colors | no | Since 1.9.0: keep event colors, for all directions. Same default as the app: on, except for busy_only |
set_sync_paused
Section titled “set_sync_paused”Sets a target state rather than toggling: pausing an already paused sync changes nothing (changed: false). For two-way syncs it applies to both directions. Pausing deletes nothing. Only for syncs whose target calendar is released for syncs; syncs stopped by the plan, a missing calendar or an ongoing change are not resumed. Annotation: destructiveHint: true.
| Parameter | Required | Description |
|---|---|---|
ref | yes | ref from a current list_syncs result |
paused | yes | true = paused, false = running |
preview_delete_sync
Section titled “preview_delete_sync”Shows what deleting a sync would do, without deleting anything: which calendars it connects and how many copies would be removed (copies_to_remove, counted from the stored mappings). Returns a confirmation_token, valid for 10 minutes, only for this access and exactly this sync. Read-only.
| Parameter | Required | Description |
|---|---|---|
ref | yes | ref from a current list_syncs result |
delete_sync
Section titled “delete_sync”Deletes the sync — only with the confirmation_token from preview_delete_sync and only after you agreed in the chat. Both directions of a two-way sync end together; all copies in the target calendar are removed in the background, the original events stay untouched. Cannot be undone. Response: status: "deleted_cleanup_pending", copies_removed. An expired, forged or other-sync token deletes nothing. Annotation: destructiveHint: true.
| Parameter | Required | Description |
|---|---|---|
ref | yes | The same ref as in the preview |
confirmation_token | yes | Token from preview_delete_sync |
Changing rules, reversing direction and syncs with other people are deliberately only available in the app.
Subscribe-calendar tools
Section titled “Subscribe-calendar tools”Seven tools require the separate, explicit publisher.manage permission. It applies to all subscribe calendars owned by your account, independently of the calendars selected for private calendar access. Existing connections do not receive this permission automatically; grant it when connecting, then reload the client’s tool list. These tools cost 0 credits; Publisher plan limits still apply.
Both sandbox and live calendars have publicly accessible pages and feeds. Sandbox adds a test label; it is not private storage. Only publish content you have explicitly approved for public use. Removing content cannot recall copies already fetched by subscribers. Calendar apps choose when to refresh their feeds.
| Tool | Inputs and result |
|---|---|
list_publisher_calendars | No inputs. Lists your live and sandbox calendars, event counts, page/feed URLs and plan usage. |
create_publisher_calendar | Required: name, IANA timezone. Optional: live (default false), description, site URL, language, color, organizer and event visibility. Returns page/feed URLs and embed markup. Confirm public content first; before the first live calendar, the assistant explains the linked subscribe-calendar terms and DPA addendum. Retrying creates another calendar. |
update_publisher_calendar | calendar_id plus changed fields. Overwrites only the supplied name, description, timezone, website, language, color, organizer or page event visibility. Does not change sandbox/live mode. |
write_publisher_events | calendar_id, events with stable external_id and event data, and/or delete_external_ids: at most 100 operations combined. Existing IDs are updated; IDs selected for deletion are removed. Returns per-item results and failure count; successful items remain applied when other items fail. |
list_publisher_events | calendar_id, optional pagination. Lists stored events in an owned calendar, up to 100 per page. |
get_publisher_stats | calendar_id. Returns aggregate subscriber/click statistics and plan usage, without subscriber identities. |
get_subscribe_button | calendar_id, optional label, color and language. Returns embed markup and subscribe links; does not install anything on a website. |
Publisher reads declare readOnlyHint: true, destructiveHint: false and openWorldHint: false. Creation, metadata updates and event writes declare readOnlyHint: false, destructiveHint: true and openWorldHint: true: they disclose public content, overwrite existing data or remove events. All except calendar creation are idempotent. Deleting an entire subscribe calendar is available through the Publisher API, not these tools.
Logging
Section titled “Logging”Every tool call lands in the access log as metadata — timestamp, tool, calendars concerned, outcome. Never the content of your events, never the search text, never the feedback wording.
As of server version 1.11.1. The server is listed in the official MCP Registry as de.kalender-sync/kalender-sync. It rebuilds the tool list on every connection, but clients cache it — after a permission change you have to reload it in your client.