Enables reading and creating events in Apple Calendar on macOS, including listing calendars, searching events, creating new events, and finding free time slots.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@apple-calendar-mcp What's on my calendar for tomorrow?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets an AI assistant read and create events in Apple Calendar — and work out when you actually have time.
macOS only. It talks to EventKit, Apple's own calendar framework, which has no cross-platform equivalent.
claude mcp add apple-calendar -- npx -y @redpop/apple-calendar-mcpNo Xcode, no Swift toolchain, no repository clone. The signed helper binary ships inside the package.
Most calendar integrations answer what is on my calendar. This one also answers when am I free:
"Find me two hours for deep work this week, outside meetings"
"When could I fit a 30-minute call with someone in Berlin?"
"Book focus time Thursday morning"find_free_time returns the open gaps, not the busy blocks. It understands
that "work" means weekdays during working hours, that "personal" means any
day, and that all-day events usually shouldn't count as busy.
It can also keep a buffer around each meeting, because a gap wedged directly between two calls is free on paper and useless in practice.
Alongside that, the usual: list calendars, read events in a range with optional text search, create, update and delete events with location, notes, alarms, all-day or timed. Recurring events come back as individual occurrences, not as the master event — a detail AppleScript-based servers routinely get wrong.
Changing or deleting an occurrence of a recurring event requires saying explicitly whether you mean just that one or every later one too. There is no default for that, because "cancel this Tuesday" and "never again" are not the kind of thing to guess at.
Full parameter reference: docs/tools.md.
Related MCP server: kelly
macOS 14 (Sonoma) or newer
Node.js 20 or newer
Nothing else. Building from source additionally needs Xcode Command Line Tools, but installing from npm does not.
1. Add the server to your client.
claude mcp add apple-calendar -- npx -y @redpop/apple-calendar-mcpQuit Claude Desktop first (Cmd+Q) — it rewrites its config on exit, so
editing while it runs discards your change. Then add to
~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"apple-calendar": {
"command": "npx",
"args": ["-y", "@redpop/apple-calendar-mcp"]
}
}
}Any client that speaks MCP over stdio works. The command is npx, the
arguments are -y @redpop/apple-calendar-mcp, and no environment variables
are needed.
2. Grant calendar access on first use.
Ask your assistant "what calendars do I have?". A system dialog appears asking to let calendar-helper — not your assistant, the helper itself — access your calendar.
Confirm it, then open System Settings → Privacy & Security → Calendars → calendar-helper → Options… and make sure Full Access is selected, not "Add Only". Read-only access is not enough; the helper checks for full access at startup.
This one dialog is the only manual step, and no package format can take it away. It appears once and survives updates.
macOS grants calendar permission to the responsible parent process, not to the program actually asking. An AI client that declares no calendar usage in its bundle therefore locks out everything it starts — silently, with no dialog and no entry in System Settings. Several MCP calendar servers work around this by telling you to launch your client from a terminal.
This one doesn't need that. The helper disclaims that inherited responsibility at startup and becomes its own permission identity, so macOS reads the usage description from its bundle and prompts under its own name. One grant then covers every client on the machine.
The full story: docs/architecture.md.
npx -y @redpop/apple-calendar-mcp@latestYour calendar grant survives updates: the helper is installed to a fixed path, and macOS binds the grant to that path rather than to the binary's contents.
Remove the apple-calendar entry from your client's MCP configuration and
restart it. Then delete the helper and its permission:
rm -rf ~/Library/Application\ Support/apple-calendar-mcpThe entry under System Settings → Privacy & Security → Calendars stays behind — macOS keeps those even when the binary is gone. Switch it off there if you want it revoked.
git clone https://github.com/redpop/apple-calendar-mcp.git
cd apple-calendar-mcp
npm install && npm run build && ./swift/build.shThen point your client at dist/index.js with node instead of using npx.
Without a Developer ID certificate the helper is signed ad-hoc, and macOS
then ties the calendar grant to the exact build — expect a new permission
dialog after every rebuild.
docs/architecture.md — how the two halves fit
together and the whole TCC permission story
docs/tools.md — every tool parameter, defaults, and
the all-day alarm rule
docs/cli.md — the standalone calendar-helper command,
useful for testing without an MCP client
docs/troubleshooting.md — common errors and
how to fix them
Everything runs locally. Calendar data goes from EventKit to the helper to the MCP server to your client, and nowhere else. There is no network code in this project.
MIT — see LICENSE.
Creates a new event. Without calendarId the default calendar is used. Read-only calendars are rejected. For all-day events, alarms are floored to whole days and placed at 09:00, matching Calendar.app. Never modifies or deletes existing events — neither is currently possible.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End, ISO 8601 with offset. For all-day events (allDay: true) both common conventions are accepted and normalised to the same day: the last day included (…T23:59:59) or midnight of the following day (…T00:00:00 of the next date). | |
| url | No | Associated URL, for example a meeting link | |
| notes | No | Free-text note attached to the event | |
| start | Yes | Start, ISO 8601 with offset | |
| title | Yes | Title of the event | |
| allDay | No | All-day event. When true, only the calendar days of start and end are used. | |
| location | No | Location, as shown in Calendar.app | |
| calendarId | No | Calendar to create the event in. Defaults to the system default calendar. | |
| alarmMinutesBefore | No | Alarms in minutes before the start. For all-day events these are floored to whole days and placed at 09:00, matching Calendar.app. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is not read-only and not destructive, but the description adds valuable context: read-only calendar rejection, all-day alarm flooring to 09:00, and the explicit note that existing events are never modified or deleted. These are behaviors beyond what annotations convey, giving the agent a strong understanding of side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The main purpose is stated first, followed by essential caveats. Every sentence carries useful information, and the structure is clean and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description covers the most critical behaviors (default calendar, read-only rejection, alarm handling, and non-destructiveness). It does not mention the return value, but for a create operation the agent can reasonably infer the created event is returned. Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters (100%), so baseline is 3. The description adds meaning for calendarId (default behavior) and alarmMinutesBefore (all-day flooring), which are not fully explained in the schema. It does not add semantics for every parameter, but the key ones are clarified, exceeding the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates a new event and describes the primary behavior (default calendar, read-only rejection). The statement 'Never modifies or deletes existing events' explicitly differentiates it from update_event and delete_event, making its purpose unmistakable even without naming siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use it: default calendar behavior and the rejection of read-only calendars. It implicitly contrasts with update/delete via the 'never modifies or deletes' clause, but does not explicitly name alternatives or give conditions like 'use list_calendars to find a calendarId.' Still, the guidance is clear enough for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes an event. Get eventIdentifier from list_events. For a recurring event, also pass occurrenceDate to name the instance and span to say how far the deletion reaches — this removes only that occurrence, future removes it and every later one. There is no undo, and span is not optional for recurring events for that reason. Read-only calendars are rejected. Returns the event as it was before deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| span | No | How far the change reaches on a recurring event. 'this' affects only the occurrence named by occurrenceDate; 'future' affects that occurrence and every later one. Required for recurring events, ignored otherwise. | |
| occurrenceDate | No | The occurrenceDate of the specific instance, exactly as returned by list_events. Required for recurring events. | |
| eventIdentifier | Yes | Identifier of the event, from list_events. For a recurring event this names the series, not one occurrence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses the irreversible nature ('There is no undo'), the span semantics for recurring events, and the rejection of read-only calendars. It also states the return value ('Returns the event as it was before deletion'), which is not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense. It front-loads the core action, then layers in usage details for recurring events and constraints, with zero filler. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with recurring-event complexity and no output schema, the description covers everything an agent needs: how to identify the target, how to scope deletions, the irreversibility, a key rejection case, and the return value. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers all parameters with descriptions, the tool description adds crucial semantic context: how to obtain eventIdentifier, when occurrenceDate is required, and how span controls scope. It explains the interplay between parameters, which goes beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Deletes an event') and the resource ('an event'), and explicitly ties the eventIdentifier to list_events, distinguishing it from update_event and create_event. It also covers recurring-event specifics, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs the agent to get eventIdentifier from list_events, explains the required parameters for recurring events (occurrenceDate and span), and states that span is mandatory for recurring events. It also warns that read-only calendars are rejected, which tells the agent when not to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds free slots of at least durationMinutes. activityDomain controls days and hours together: work means Mon-Fri 09:00-18:00, personal every day at the same hours, unrestricted every day around the clock. workingHours overrides only the hours. bufferMinutes keeps time free around each busy event, so a slot wedged between two meetings is not offered as usable. Returns the free gaps, not the busy events — use list_events for those. Creates nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End of the search window | |
| start | Yes | Start of the search window | |
| calendarIds | No | Treat these calendars as busy. Defaults to all of them. | |
| ignoreAllDay | No | All-day events do not count as busy | |
| workingHours | No | Overrides only the hours of the activityDomain, not which days it covers | |
| bufferMinutes | No | Free time to keep before and after each busy event, in minutes. Use this when a slot pressed directly between two meetings would not actually be usable. | |
| activityDomain | No | work: Mon-Fri 09:00-18:00. personal: every day 09:00-18:00. unrestricted: every day, around the clock. | work |
| durationMinutes | Yes | Required duration in minutes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'Creates nothing'. It adds rich behavioral context beyond annotations: how activityDomain and workingHours interact, and that bufferMinutes excludes slots wedged between meetings. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, front-loaded with the core purpose, then elaborating on key parameters and the return type. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description covers all essential behavior: what it returns (free gaps), how parameters affect results, and which sibling to use for busy events. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds significant meaning: it explains that activityDomain controls days and hours together, workingHours overrides only hours, and bufferMinutes preserves free time around busy events. This goes well beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds free slots of at least durationMinutes, with a specific verb and resource. It explicitly distinguishes itself from list_events by noting it returns free gaps, not busy events, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance: use this tool to find free time, and use list_events for busy events. This provides a clear alternative and the condition that selects it, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every calendar configured in macOS Calendar, including iCloud ones. Returns id, title, type, source, color and allowsModifications for each. Does not read events — list_events does that.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description adds value by specifying the return fields and scope (including iCloud), giving the agent concrete expectations without redundancy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The main action is front-loaded, followed by return details and the sibling differentiation. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only tool, the description covers what it does, what it returns, and how it differs from the obvious sibling. Annotations cover safety, so no behavioral gaps remain. The agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description doesn't need to add parameter semantics since none exist; it instead focuses on return values, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every calendar in macOS Calendar, including iCloud ones, and specifies the exact return fields. It also explicitly distinguishes itself from list_events, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Does not read events — list_events does that,' which provides a clear when-not-to-use and names the alternative. This gives the agent direct routing guidance between the two sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads events in a date range. Recurring events are returned as individual occurrences. All-day events additionally carry startDay and endDay as plain dates, where endDay means the last day included. Changes nothing. For free gaps rather than busy events, use find_free_time.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | End of the range, ISO 8601 with offset | |
| query | No | Free-text filter applied to titles and notes | |
| start | Yes | Start of the range, ISO 8601 with offset | |
| maxResults | No | Maximum number of events to return | |
| calendarIds | No | Restrict to these calendars. Defaults to all of them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces with 'Changes nothing.' It adds valuable behavior beyond annotations: recurring events are expanded to occurrences, and all-day events carry startDay/endDay with a clear definition of endDay. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, with the core purpose front-loaded. Every sentence adds information: the scope, the recurring/all-day behavior, and the sibling pointer. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters (2 required) and no output schema, but the description covers key behavioral expectations (recurring expansion, all-day fields) and offers a relevant alternative. It doesn't mention pagination or output structure, but these are partially handled by maxResults in the schema, so the coverage is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (start, end, query, maxResults, calendarIds) are already fully documented. The description adds no parameter-specific semantics beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pairing ('Reads events in a date range') that clearly distinguishes it from mutating siblings like create_event/update_event/delete_event. It further contrasts with find_free_time by naming it explicitly, so an agent knows exactly what this tool does and what it doesn't.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit alternative ('For free gaps rather than busy events, use find_free_time') and states the behavior for recurring and all-day events. It lacks an explicit 'when not to use' for other siblings, but the read-only nature and the free-time pointer cover the main usage decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes an existing event. Only the fields you pass are changed; anything left out keeps its current value. Get eventIdentifier from list_events. For a recurring event, also pass occurrenceDate to name the instance and span to say how far the change reaches — this affects only that occurrence, future affects it and every later one. Read-only calendars are rejected. Alarms, if given, replace all existing ones.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | New end, ISO 8601 with offset | |
| url | No | New associated URL. An empty string removes it. | |
| span | No | How far the change reaches on a recurring event. 'this' affects only the occurrence named by occurrenceDate; 'future' affects that occurrence and every later one. Required for recurring events, ignored otherwise. | |
| notes | No | New notes, replacing the previous ones | |
| start | No | New start, ISO 8601 with offset | |
| title | No | New title | |
| allDay | No | Turn the event into an all-day event, or back | |
| location | No | New location | |
| occurrenceDate | No | The occurrenceDate of the specific instance, exactly as returned by list_events. Required for recurring events. | |
| eventIdentifier | Yes | Identifier of the event, from list_events. For a recurring event this names the series, not one occurrence. | |
| alarmMinutesBefore | No | Replaces all existing alarms. Pass an empty array to remove them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds rich behavioral detail: only passed fields change, others keep current values; recurring event behavior with span; read-only calendar rejection; and alarm replacement semantics. It also explains how to obtain eventIdentifier. This goes well beyond the annotations and discloses important side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each carrying meaningful information without redundancy. It front-loads the primary action and partial-update behavior, then addresses recurring events, read-only rejection, and alarms in a logical order. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 11 parameters, the description covers the most critical aspects: partial update, recurring event logic, read-only rejection, and alarm replacement. It does not mention return values (no output schema), error handling, or edge cases like date format validation, but these are arguably less essential. Given the complexity, it is sufficiently complete for an agent to call it correctly in common scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have individual descriptions. The tool description adds global semantics: partial update behavior, recurring event handling (span and occurrenceDate interplay), and alarm replacement. It also gives provenance for eventIdentifier. This adds value beyond the schema's per-field descriptions, so a score above the baseline 3 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Changes an existing event.' It also clarifies the partial-update semantics, which is the core behavior. It implicitly distinguishes from siblings like create_event and delete_event, and the phrase 'Get eventIdentifier from list_events' ties it to the correct data source. This is a precise, non-tautological purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives specific guidance: get the identifier from list_events, and for recurring events pass occurrenceDate and span with explicit meaning of each span value. It also notes that read-only calendars are rejected, implying you should ensure the calendar is writable. It does not explicitly name alternatives (e.g., 'use create_event for new events'), but the context of updating an existing event is clear. This is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1create_eventdelete_eventfind_free_timelist_calendarslist_eventsupdate_eventScored across 6 tools
Each tool has a distinct purpose: listing calendars, listing events, creating/updating/deleting events, and finding free time. Even list_events and find_free_time are clearly differentiated by their descriptions.
Tool names follow a consistent verb_noun pattern with snake_case (list_events, list_calendars, create_event, update_event, delete_event, find_free_time). The naming is predictable and uniform.
Six tools cover the core calendar operations without unnecessary redundancy. This is a well-scoped set for the stated purpose.
The toolset provides full CRUD for events, calendar listing, and free-time lookup. No essential calendar operations are missing for typical agent workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
