Home Assistant MCP Server

Official

by homeassistant-ai

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Create or Update Calendar Event

ha_config_set_calendar_event

Destructive

Create or update Home Assistant calendar events, including recurring series, by specifying a calendar entity, summary, and start and end times.

Instructions

Create a new event in a calendar, or update an existing one.

Creates a one-off event via the calendar.create_event service, or a recurring series via the WebSocket calendar/event/create command when rrule is provided (the REST service schema does not accept recurrence rules). Passing uid switches to update mode, which uses the WebSocket calendar/event/update command — HA registers no REST service for updating an event.

When NOT to use:

To retrieve calendar events, use ha_config_get_calendar_events.
To delete an event, use ha_config_remove_calendar_event.
To find the uid of an event to update, use ha_config_get_calendar_events; this tool does not search.

Passing date-only values (YYYY-MM-DD) for both start and end creates an all-day event; passing full ISO datetimes creates a timed event. The two forms cannot be mixed — a date-only start with a datetime end (or vice versa) is rejected.

An update replaces the whole event rather than patching it, so summary, start and end stay required in update mode, and a description or location that is not re-supplied is cleared. An rrule is the exception: Home Assistant accepts a new rule but has no way to express "no recurrence", so an existing rule survives an update that omits it. Delete the event and create it again to drop the recurrence.

Not every calendar integration supports event creation; recurring events additionally require the integration to support recurrence (the built-in Local Calendar does). Update support is narrower still: Local Calendar implements it, while the core Google Calendar and CalDAV integrations do not.

EXAMPLES:

Create: ha_config_set_calendar_event("calendar.family", summary="Doctor appointment", start="2024-01-15T14:00:00", end="2024-01-15T15:00:00")
Recurring (every Monday, 10 occurrences): ha_config_set_calendar_event("calendar.work", summary="Team meeting", start="2024-01-15T10:00:00", end="2024-01-15T11:00:00", rrule="FREQ=WEEKLY;BYDAY=MO;COUNT=10")
Update this and all later occurrences: ha_config_set_calendar_event("calendar.work", summary="Team meeting (new time)", start="2024-02-05T11:00:00", end="2024-02-05T12:00:00", uid="recurring-event-67890", recurrence_id="20240205T100000", recurrence_range="THISANDFUTURE")

If a Claude Desktop user gets a 4-minute timeout with no result on this call, read the target back before repeating it, and tell them to wait a few seconds before clicking the manual-approve button, as clicking it too quickly is known to cause hangs in Claude Desktop. This workaround is specific to Claude Desktop.

Input Schema

Name	Required	Description
`end`	Yes	Event end date or datetime in ISO format. For all-day events (date-only) the end date is exclusive; a single-day all-day event needs end = start + 1 day.
`uid`	No	UID of an existing event to update. Omit to create a new event.
`rrule`	No	RFC 5545 recurrence rule, without 'RRULE:' prefix (e.g., 'FREQ=WEEKLY;BYDAY=MO' or 'FREQ=MONTHLY;BYDAY=3SA'). Creates a recurring event series.
`start`	Yes	Event start date or datetime in ISO format
`summary`	Yes	Event title/summary
`location`	No	Event location
`entity_id`	Yes	Calendar entity ID (e.g., 'calendar.family')
`description`	No	Event description
`recurrence_id`	No	Only meaningful with 'uid': identifies one occurrence of a recurring series to update.
`recurrence_range`	No	Only meaningful with 'uid': 'THISANDFUTURE' to update this and all following occurrences. Home Assistant compares this value verbatim, so no other spelling (including 'THIS_AND_FUTURE') selects the range.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv8.6.0Oct 1, 2026

changedInput schema / properties / description / description

Previous value: -"Optional event description"New value: +"Event description"

changedInput schema / properties / location / description

Previous value: -"Optional event location"New value: +"Event location"

addedInput schema / properties / recurrence_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only meaningful with 'uid': identifies one occurrence of a recurring series to update."
+}

addedInput schema / properties / recurrence_range

Added value: +{
+  "anyOf": [
+    {
+      "const": "THISANDFUTURE",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Only meaningful with 'uid': 'THISANDFUTURE' to update this and all following occurrences. Home Assistant compares this value verbatim, so no other spelling (including 'THIS_AND_FUTURE') selects the range."
+}

changedInput schema / properties / rrule / description

Previous value: -"Optional RFC 5545 recurrence rule, without 'RRULE:' prefix (e.g., 'FREQ=WEEKLY;BYDAY=MO' or 'FREQ=MONTHLY;BYDAY=3SA'). Creates a recurring event series."New value: +"RFC 5545 recurrence rule, without 'RRULE:' prefix (e.g., 'FREQ=WEEKLY;BYDAY=MO' or 'FREQ=MONTHLY;BYDAY=3SA'). Creates a recurring event series."

addedInput schema / properties / uid

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "UID of an existing event to update. Omit to create a new event."
+}

First observedv7.14.2Jul 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructive=true and idempotent=false, but the description adds substantial non-obvious behavior: updates replace the whole event (non-patch), un-supplied description/location are cleared, rrule survives an omitted update (HA cannot express 'no recurrence'), and integration support varies for create/recurrence/update. This is exactly the kind of consequence-level detail annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Despite its length it is well front-loaded and organized with headers and examples, and each section carries decision-relevant content. The trailing Claude Desktop timeout paragraph is loosely scoped operational advice that sits outside the tool's core contract, costing it a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 params, an output schema, and full annotation coverage, the description supplies everything else an agent needs: mode selection, mixing rules, replacement semantics, recurrence quirks, and integration support limitations. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, and the description exceeds it by explaining the all-day vs timed distinction, the date/datetime mixing rejection, and the interplay of uid/recurrence_id/recurrence_range for partial-series updates. It stops short of fully restating every parameter, hence 4 rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (create/update calendar event) and then splits the behavior precisely: create via REST service, recurring series via WebSocket when rrule is present, update mode when uid is passed. It also explicitly names sibling tools it is not, so an agent can route correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes an explicit 'When NOT to use' block routing retrievals to ha_config_get_calendar_events and deletions to ha_config_remove_calendar_event, plus a note that finding a uid requires the get tool. It also specifies when create vs update fires (uid presence, rrule presence), covering both alternatives and triggers.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server