mcp-icloud 2.1.1 → 2.1.3

package/PRIVACY.md

@@ -0,0 +1,55 @@
+# Privacy policy
+
+Effective 10 August 2026. Applies to the mcp-icloud server (the software you
+run), not to any AI client you connect it to.
+
+## The short version
+
+mcp-icloud runs on your machine and works for you. It has no servers of its
+own, no analytics, no telemetry, and no way to see your data. The author
+never receives anything.
+
+## What the software touches, and where it goes
+
+When a connected AI client (Claude Desktop, for example) calls a tool, the
+server reads or writes data in your Apple services: mail, calendar events,
+contacts, reminders, notes, messages, and Safari tabs. Two things happen
+with that data, and nothing else.
+
+First, tool results are returned to the AI client that asked for them. What
+that client does with the data is governed by its own privacy policy, not
+this one. Nothing is sent anywhere unless a client you connected asks.
+
+Second, in cloud mode the server talks to Apple's servers on your behalf
+(imap.mail.me.com, smtp.mail.me.com, caldav.icloud.com,
+contacts.icloud.com), over TLS, authenticated with credentials you
+provided. In local mode the server makes no network connections at all; it
+drives the apps already on your Mac, and macOS asks for your consent per
+app before any of that works. You can revoke that consent at any time in
+System Settings under Privacy and Security.
+
+## Credentials
+
+Cloud mode needs your iCloud address and an app-specific password. You
+store them yourself, either in a local .env file or in the macOS Keychain
+when you install the desktop extension. The server reads them once at
+startup, sends them only to Apple, and never writes them to any log.
+Diagnostics print a fixed mask instead of the value. Local mode needs no
+credentials at all.
+
+## What is kept
+
+Nothing. The server is stateless: no database, no cache, no files written.
+When it stops, nothing of yours remains in it.
+
+## Third parties
+
+There are none. No data is sold, shared, or transferred to anyone. The only
+parties that ever see your data are Apple (which already has it) and the AI
+client you chose to connect.
+
+## Changes and contact
+
+Changes to this policy are made in this file, in the open, with the
+repository's history as the record. Questions and concerns:
+https://github.com/MrGo2/icloud-mcp/issues

package/README.md

@@ -5,17 +5,22 @@
 
 <div align="center">
 
+[![npm](https://img.shields.io/npm/v/mcp-icloud?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/mcp-icloud)
 [![CI](https://github.com/MrGo2/icloud-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MrGo2/icloud-mcp/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/MrGo2/icloud-mcp?style=flat-square&color=8250df)](https://github.com/MrGo2/icloud-mcp/releases/latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=flat-square&logo=node.js&logoColor=white)](package.json)
 [![MCP](https://img.shields.io/badge/MCP-SDK%20v2-a371f7?style=flat-square)](https://modelcontextprotocol.io)
+[![icloud-mcp MCP server](https://glama.ai/mcp/servers/MrGo2/icloud-mcp/badges/score.svg)](https://glama.ai/mcp/servers/MrGo2/icloud-mcp)
 
 </div>
 
+<img src="assets/demo.gif" alt="Claude creating a note, a reminder and a calendar event through icloud-mcp" width="100%">
+
 icloud-mcp covers seven Apple services with two interchangeable backends, and as far as we know it is the only MCP server that does. In local mode it drives the native macOS apps through AppleScript: no credentials, no network, and it reaches the services the iCloud protocols do not expose (Reminders, Notes, Messages, Safari). In cloud mode it speaks IMAP/SMTP, CalDAV and CardDAV instead, so it runs on any machine, not just a Mac. The `set-mode` tool switches between the two at runtime, without a restart.
 
 [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=icloud&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-icloud%22%5D%7D)
+[![Install in Cursor](https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=icloud&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1pY2xvdWQiXX0=)
 
 ## Features
 
@@ -29,6 +34,10 @@ Credentials are never logged. `ICLOUD_APP_PASSWORD` is read once at startup and
 
 Every tool argument is validated against a zod schema before the handler runs. Arguments are also coerced at each AppleScript interpolation site, so a value that is not a number cannot reach a script template.
 
+## Privacy Policy
+
+The server collects nothing and keeps nothing: no telemetry, no analytics, no state on disk. Your data moves only between your machine, the AI client you connect and Apple's services. The full policy, covering collection, storage, third-party sharing, retention and contact, is in [PRIVACY.md](PRIVACY.md).
+
 ## Tools
 
 Tools marked local only return an error in cloud mode, because the iCloud protocols do not expose those services.
@@ -108,12 +117,26 @@ Reading requires the [`imsg`](https://github.com/steipete/imsg) CLI and Full Dis
 
 ### Tool annotations (MCP hints)
 
-Every tool declares its behaviour explicitly instead of relying on the spec defaults, which are deliberately pessimistic. All `list-*`, `read-*`, `search-*` and `get-*` tools, plus `about` and `check-auth-status`, are marked read-only. The four destructive tools (`delete-event`, `delete-contact`, `delete-reminder`, `close-safari-tab`) carry `destructiveHint`. Tools that reach the network or another person carry `openWorldHint`: all Email and Calendar tools, `send-message`, `react-message` and `open-safari-url`. The read-only tools plus `mark-as-read`, `complete-reminder`, `update-reminder`, `update-event` and `set-mode` are marked idempotent.
+Every tool declares its behaviour explicitly instead of relying on the spec defaults, which are deliberately pessimistic. All `list-*`, `read-*`, `search-*` and `get-*` tools, plus `about` and `check-auth-status`, are marked read-only. Nine tools carry `destructiveHint`: the four deletions (`delete-event`, `delete-contact`, `delete-reminder`, `close-safari-tab`), the three that reach another person irrevocably (`send-email`, `send-message`, `react-message`) and the two in-place updates (`update-event`, `update-reminder`). Tools that reach the network or another person carry `openWorldHint`: all Email and Calendar tools, `send-message`, `react-message` and `open-safari-url`. The read-only tools plus `mark-as-read`, `complete-reminder`, `update-reminder`, `update-event` and `set-mode` are marked idempotent.
 
 ## Installation
 
 Requires Node.js 20 or newer.
 
+### Let your AI install it
+
+Paste this into Claude, Claude Code, Cursor, ChatGPT or any agent with shell or config access:
+
+```
+Install the iCloud MCP server. It is the npm package "mcp-icloud" (Node 20+),
+stdio transport, server name "icloud", command "npx" with args ["-y", "mcp-icloud"].
+On Claude Code run: claude mcp add --transport stdio icloud -- npx -y mcp-icloud
+For other clients, add that command/args pair to the client's MCP config file.
+Local mode (default) needs macOS; cloud mode needs env vars USE_LOCAL_MODE=false,
+ICLOUD_EMAIL and ICLOUD_APP_PASSWORD (app-specific password from account.apple.com).
+Docs: https://github.com/MrGo2/icloud-mcp
+```
+
 ### Claude Desktop
 
 Add to `claude_desktop_config.json`:

package/calendar/index.js

@@ -182,7 +182,7 @@ const calendarTools = [
     name: 'list-events',
     outputSchema: listOutput('Calendar events'),
     title: 'List Events',
-    description: 'Lists upcoming calendar events',
+    description: 'Lists upcoming calendar events within a look-ahead window (30 days by default, up to 365). Each event carries its title, start and end times, and the ref handle that update-event and delete-event take as their eventUrl argument.',
     inputSchema: {
       count: z.number().int().min(1).max(50).optional().describe('Number of events to retrieve (default: 25, max: 50)'),
       daysAhead: z.number().int().min(1).max(365).optional().describe('Number of days to look ahead (default: 30)')
@@ -218,7 +218,7 @@ const calendarTools = [
       description: z.string().optional().describe('New description (optional)'),
       location: z.string().optional().describe('New location (optional)')
     },
-    annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":true},
     handler: withErrorHandler(handleUpdateEvent, 'update-event')
   },
   {

package/calendar/local-client.js

@@ -3,7 +3,7 @@
  * Accesses Calendar.app via AppleScript
  */
 
-const { runAppleScript, runJXA, escapeAppleScript, escapeJXA, asInt, formatAppleScriptDate } = require('../utils/applescript');
+const { runAppleScript, runJXA, escapeAppleScript, escapeJXA, asInt, appleScriptDateStmts } = require('../utils/applescript');
 const config = require('../config');
 
 /**
@@ -115,26 +115,12 @@ async function createEvent({ summary, start, end, location, description, calenda
   // Use default calendar if none specified
   const targetCalendar = calendarName || 'Calendar';
 
-  if (allDay) {
-    // All-day event
-    const script = `
-      tell application "Calendar"
-        tell calendar "${escapeAppleScript(targetCalendar)}"
-          set newEvent to make new event with properties {summary:"${escapeAppleScript(summary)}", start date:date "${formatAppleScriptDate(startDate)}", end date:date "${formatAppleScriptDate(endDate)}", allday event:true}
-          ${location ? `set location of newEvent to "${escapeAppleScript(location)}"` : ''}
-          ${description ? `set description of newEvent to "${escapeAppleScript(description)}"` : ''}
-          return uid of newEvent
-        end tell
-      end tell
-    `;
-
-    const uid = await runAppleScript(script);
-    return { success: true, id: uid, message: 'Event created successfully' };
-  } else {
-    const script = `
+  const script = `
       tell application "Calendar"
+        ${appleScriptDateStmts('newStart', startDate)}
+        ${appleScriptDateStmts('newEnd', endDate)}
         tell calendar "${escapeAppleScript(targetCalendar)}"
-          set newEvent to make new event with properties {summary:"${escapeAppleScript(summary)}", start date:date "${formatAppleScriptDate(startDate)}", end date:date "${formatAppleScriptDate(endDate)}"}
+          set newEvent to make new event with properties {summary:"${escapeAppleScript(summary)}", start date:newStart, end date:newEnd${allDay ? ', allday event:true' : ''}}
           ${location ? `set location of newEvent to "${escapeAppleScript(location)}"` : ''}
           ${description ? `set description of newEvent to "${escapeAppleScript(description)}"` : ''}
           return uid of newEvent
@@ -142,9 +128,8 @@ async function createEvent({ summary, start, end, location, description, calenda
       end tell
     `;
 
-    const uid = await runAppleScript(script);
-    return { success: true, id: uid, message: 'Event created successfully' };
-  }
+  const uid = await runAppleScript(script);
+  return { success: true, id: uid, message: 'Event created successfully' };
 }
 
 /**
@@ -155,10 +140,17 @@ async function createEvent({ summary, start, end, location, description, calenda
  */
 async function updateEvent(eventId, { summary, start, end, location, description }) {
   let updateCommands = [];
+  let dateSetup = [];
 
   if (summary) updateCommands.push(`set summary of theEvent to "${escapeAppleScript(summary)}"`);
-  if (start) updateCommands.push(`set start date of theEvent to date "${formatAppleScriptDate(new Date(start))}"`);
-  if (end) updateCommands.push(`set end date of theEvent to date "${formatAppleScriptDate(new Date(end))}"`);
+  if (start) {
+    dateSetup.push(appleScriptDateStmts('newStart', new Date(start)));
+    updateCommands.push('set start date of theEvent to newStart');
+  }
+  if (end) {
+    dateSetup.push(appleScriptDateStmts('newEnd', new Date(end)));
+    updateCommands.push('set end date of theEvent to newEnd');
+  }
   if (location !== undefined) updateCommands.push(`set location of theEvent to "${escapeAppleScript(location || '')}"`);
   if (description !== undefined) updateCommands.push(`set description of theEvent to "${escapeAppleScript(description || '')}"`);
 
@@ -168,6 +160,7 @@ async function updateEvent(eventId, { summary, start, end, location, description
 
   const script = `
     tell application "Calendar"
+      ${dateSetup.join('\n      ')}
       set allCalendars to calendars
       repeat with cal in allCalendars
         try

package/contacts/index.js

@@ -260,7 +260,7 @@ const contactsTools = [
     name: 'list-contacts',
     outputSchema: listOutput('Contacts'),
     title: 'List Contacts',
-    description: 'Lists contacts from your iCloud address book',
+    description: 'Lists contacts from the user\'s address book, up to 50 per call, including the handle that read-contact and delete-contact take. For a targeted lookup, search-contacts filters by name, email or phone instead of paging through the full list.',
     inputSchema: {
       count: z.number().int().min(1).max(50).optional().describe('Number of contacts to retrieve (default: 25, max: 50)')
     },
@@ -292,7 +292,7 @@ const contactsTools = [
   {
     name: 'create-contact',
     title: 'Create Contact',
-    description: 'Creates a new contact',
+    description: 'Creates a contact in the user\'s address book (Contacts.app in local mode, iCloud over CardDAV in cloud mode). Every field is optional, so pass at least a name (displayName, or firstName and lastName) along with any known email, phone, organization, job title or notes.',
     inputSchema: {
       displayName: z.string().optional().describe('Full display name'),
       firstName: z.string().optional().describe('First name'),
@@ -309,7 +309,7 @@ const contactsTools = [
   {
     name: 'delete-contact',
     title: 'Delete Contact',
-    description: 'Deletes a contact',
+    description: 'Permanently deletes a contact from the user\'s address book. Takes the handle returned by list-contacts or search-contacts; there is no undo through this server.',
     inputSchema: {
       contactUrl: z.string().describe('URL or ID of the contact to delete (from list-contacts output)')
     },

package/email/index.js

@@ -216,7 +216,7 @@ const emailTools = [
   {
     name: 'send-email',
     title: 'Send Email',
-    description: 'Composes and sends an email',
+    description: 'Sends an email immediately from the user\'s account to one or more comma-separated recipients, with optional CC, BCC and HTML body. Cloud mode delivers over SMTP and returns the new message ID; local mode sends through Mail.app, which only sends plain text and returns no ID. There is no draft step, so the message goes out as soon as the tool runs.',
     inputSchema: {
       to: z.string().describe('Recipient email address(es), comma-separated'),
       cc: z.string().optional().describe('CC recipient(s), comma-separated'),
@@ -225,14 +225,14 @@ const emailTools = [
       body: z.string().describe('Email body content'),
       isHtml: z.boolean().optional().describe('Whether the body is HTML (default: false)')
     },
-    annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},
+    annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},
     handler: withErrorHandler(handleSendEmail, 'send-email')
   },
   {
     name: 'search-emails',
     outputSchema: listOutput('Matching emails'),
     title: 'Search Emails',
-    description: 'Search for emails by criteria',
+    description: 'Searches one mail folder (inbox by default) by free text, sender, subject and unread state; the filters combine as AND. Results carry the same summary fields as list-emails, including the ref handle that read-email and mark-as-read take.',
     inputSchema: {
       query: z.string().optional().describe('Text to search in email content'),
       from: z.string().optional().describe('Filter by sender'),

package/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * iCloud MCP Server v2.1.1
+ * iCloud MCP Server
  *
  * Provides Claude with access to Apple services:
  * - Email (via IMAP/SMTP or Mail.app)
@@ -21,6 +21,7 @@ const { McpServer } = require('@modelcontextprotocol/server');
 const { serveStdio } = require('@modelcontextprotocol/server/stdio');
 
 const config = require('./config');
+const { version } = require('./package.json');
 const { getMode, onModeChange } = require('./mode');
 
 // Import all modules - tools are always available, handlers check mode
@@ -56,11 +57,15 @@ function buildServer() {
   const server = new McpServer(
     {
       name: 'icloud-mcp',
-      version: '2.1.1',
+      version,
       title: 'iCloud MCP'
     },
     {
       capabilities: { tools: { listChanged: true } },
+      // The 41-tool list is identical in both modes (mode changes behaviour,
+      // not the roster), so clients may cache it. Without this the SDK
+      // advertises ttlMs: 0 and every 2026-era client re-fetches constantly.
+      cacheHints: { 'tools/list': { ttlMs: 3600000, cacheScope: 'public' } },
       instructions: `Access to Apple services in two modes.
 
 LOCAL (default, macOS only) drives the native apps via AppleScript.
@@ -94,7 +99,7 @@ mode returns an error. Use set-mode to switch without restarting.`
   return server;
 }
 
-console.error('[icloud-mcp] Starting iCloud MCP server v2.1.1...');
+console.error(`[icloud-mcp] Starting iCloud MCP server v${version}...`);
 console.error(`[icloud-mcp] Initial mode: ${getMode().toUpperCase()}`);
 console.error(`[icloud-mcp] Tools available: ${TOOLS.length}`);
 

package/messages/index.js

@@ -110,13 +110,13 @@ const messagesTools = [
   {
     name: 'send-message',
     title: 'Send Message',
-    description: 'Send an iMessage or SMS. IMPORTANT: Always confirm with user before sending.',
+    description: 'Sends an iMessage or SMS to a phone number or email handle, with an optional file attachment. The message is delivered as soon as the tool runs; there is no draft step and no recall.',
     inputSchema: {
       to: z.string().describe('Recipient phone number (with country code) or email'),
       body: z.string().describe('Message content'),
       file: z.string().optional().describe('Path to file attachment (optional)')
     },
-    annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},
+    annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},
     handler: withErrorHandler(async ({ to, body, file }) => {
       const modeError = requireLocalMode('send-message');
       if (modeError) return modeError;
@@ -144,7 +144,7 @@ const messagesTools = [
       chatId: z.number().int().describe('Chat ID'),
       type: z.enum(['love', 'like', 'dislike', 'laugh', 'emphasis', 'question']).describe('Reaction type')
     },
-    annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},
+    annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},
     handler: withErrorHandler(async ({ chatId, type }) => {
       const modeError = requireLocalMode('react-message');
       if (modeError) return modeError;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-icloud",
   "mcpName": "io.github.MrGo2/icloud-mcp",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "MCP server for Apple services - Email, Calendar, Contacts, Reminders, Notes, Messages and Safari - with dual local (AppleScript) and cloud (IMAP/CalDAV/CardDAV) modes",
   "main": "index.js",
   "bin": {
@@ -22,6 +22,7 @@
     "utils/",
     "LICENSE",
     "README.md",
+    "PRIVACY.md",
     "DISCLOSURE"
   ],
   "scripts": {

package/reminders/index.js

@@ -115,7 +115,7 @@ const remindersTools = [
       dueDate: z.string().optional().describe('New due date in ISO format'),
       priority: z.number().int().min(0).max(9).optional().describe('New priority level')
     },
-    annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
     handler: async ({ reminderId, ...updates }) => {
       const modeError = requireLocalMode('update-reminder');
       if (modeError) return modeError;

package/reminders/local-client.js

@@ -3,7 +3,7 @@
  * Accesses Reminders.app via AppleScript
  */
 
-const { runAppleScript, runJXA, escapeAppleScript, escapeJXA, asInt, asBool, formatAppleScriptDate } = require('../utils/applescript');
+const { runAppleScript, runJXA, escapeAppleScript, escapeJXA, asInt, asBool, appleScriptDateStmts } = require('../utils/applescript');
 
 /**
  * List all reminder lists
@@ -109,7 +109,8 @@ async function createReminder({ name, body, dueDate, listName = 'Reminders', pri
 
   if (dueDate) {
     script += `
-        set due date of newReminder to date "${formatAppleScriptDate(new Date(dueDate))}"
+        ${appleScriptDateStmts('theDue', new Date(dueDate))}
+        set due date of newReminder to theDue
     `;
   }
 
@@ -135,11 +136,16 @@ async function updateReminder(reminderId, { name, body, dueDate, priority }) {
   if (name) updateCommands.push(`set name of theReminder to "${escapeAppleScript(name)}"`);
   if (body !== undefined) updateCommands.push(`set body of theReminder to "${escapeAppleScript(body || '')}"`);
   if (priority !== undefined) updateCommands.push(`set priority of theReminder to ${asInt(priority, 0)}`);
-  if (dueDate) updateCommands.push(`set due date of theReminder to date "${formatAppleScriptDate(new Date(dueDate))}"`);
+  let dateSetup = [];
+  if (dueDate) {
+    dateSetup.push(appleScriptDateStmts('theDue', new Date(dueDate)));
+    updateCommands.push('set due date of theReminder to theDue');
+  }
   if (dueDate === null) updateCommands.push(`set due date of theReminder to missing value`);
 
   const script = `
     tell application "Reminders"
+      ${dateSetup.join('\n      ')}
       set allLists to lists
       repeat with theList in allLists
         try

package/utils/applescript.js

@@ -161,18 +161,24 @@ function asBool(value, fallback = false) {
  * @param {Date|string} date - Date to format
  * @returns {string} - AppleScript date string
  */
-function formatAppleScriptDate(date) {
+/**
+ * AppleScript statements that build a Date into `varName`.
+ * `date "August 15, 2026 6:00 PM"` literals only parse when the string matches
+ * the system locale, so the date is assembled numerically instead. Day is set
+ * to 1 first so applying the components one by one cannot overflow a month.
+ */
+function appleScriptDateStmts(varName, date) {
   const d = date instanceof Date ? date : new Date(date);
-  // Format: "January 15, 2026 at 10:30:00 AM"
-  return d.toLocaleString('en-US', {
-    year: 'numeric',
-    month: 'long',
-    day: 'numeric',
-    hour: 'numeric',
-    minute: '2-digit',
-    second: '2-digit',
-    hour12: true
-  }).replace(',', ' at');
+  if (isNaN(d.getTime())) throw new Error(`Invalid date: ${date}`);
+  const secs = d.getHours() * 3600 + d.getMinutes() * 60 + d.getSeconds();
+  return [
+    `set ${varName} to (current date)`,
+    `set day of ${varName} to 1`,
+    `set year of ${varName} to ${d.getFullYear()}`,
+    `set month of ${varName} to ${d.getMonth() + 1}`,
+    `set day of ${varName} to ${d.getDate()}`,
+    `set time of ${varName} to ${secs}`
+  ].join('\n      ');
 }
 
 /**
@@ -209,6 +215,6 @@ module.exports = {
   escapeJXA,
   asInt,
   asBool,
-  formatAppleScriptDate,
+  appleScriptDateStmts,
   AppleScriptError
 };