mcp-icloud 2.1.1

package/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+/**
+ * iCloud MCP Server v2.1.1
+ *
+ * Provides Claude with access to Apple services:
+ * - Email (via IMAP/SMTP or Mail.app)
+ * - Calendar (via CalDAV or Calendar.app)
+ * - Contacts (via CardDAV or Contacts.app)
+ * - Reminders (via Reminders.app - local only)
+ * - Notes (via Notes.app - local only)
+ * - Messages (via Messages.app - local only)
+ * - Safari (via Safari.app - local only)
+ *
+ * Modes (switchable at runtime via set-mode tool):
+ * - LOCAL: Uses AppleScript to access native macOS apps (fast, requires Mac)
+ * - CLOUD: Uses iCloud protocols (IMAP, CalDAV, CardDAV) - works from anywhere
+ */
+
+const { McpServer } = require('@modelcontextprotocol/server');
+const { serveStdio } = require('@modelcontextprotocol/server/stdio');
+
+const config = require('./config');
+const { getMode, onModeChange } = require('./mode');
+
+// Import all modules - tools are always available, handlers check mode
+const { authTools } = require('./auth');
+const { emailTools } = require('./email');
+const { calendarTools } = require('./calendar');
+const { contactsTools } = require('./contacts');
+const { remindersTools } = require('./reminders');
+const { notesTools } = require('./notes');
+const { messagesTools } = require('./messages');
+const { safariTools } = require('./safari');
+
+// All tools always available - handlers check mode and error if unsupported
+const TOOLS = [
+  ...authTools,
+  ...emailTools,
+  ...calendarTools,
+  ...contactsTools,
+  ...remindersTools,
+  ...notesTools,
+  ...messagesTools,
+  ...safariTools
+];
+
+/**
+ * Build a server instance with every tool registered.
+ *
+ * serveStdio takes a factory rather than an instance: the opening exchange
+ * decides the protocol era and pins one instance for the connection, so the
+ * same registrations have to be reproducible on demand.
+ */
+function buildServer() {
+  const server = new McpServer(
+    {
+      name: 'icloud-mcp',
+      version: '2.1.1',
+      title: 'iCloud MCP'
+    },
+    {
+      capabilities: { tools: { listChanged: true } },
+      instructions: `Access to Apple services in two modes.
+
+LOCAL (default, macOS only) drives the native apps via AppleScript.
+CLOUD uses the iCloud protocols and needs an app-specific password.
+
+Reminders, Notes, Messages and Safari are LOCAL only: calling them in CLOUD
+mode returns an error. Use set-mode to switch without restarting.`
+    }
+  );
+
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+        ...(tool.annotations ? { annotations: tool.annotations } : {})
+      },
+      tool.handler
+    );
+  }
+
+  // set-mode changes which tools actually work, so tell the client to re-read
+  // the list. Failures here are cosmetic - never take the connection down.
+  onModeChange(() => {
+    Promise.resolve(server.sendToolListChanged()).catch(() => {});
+  });
+
+  return server;
+}
+
+console.error('[icloud-mcp] Starting iCloud MCP server v2.1.1...');
+console.error(`[icloud-mcp] Initial mode: ${getMode().toUpperCase()}`);
+console.error(`[icloud-mcp] Tools available: ${TOOLS.length}`);
+
+if (getMode() === 'local') {
+  console.error('[icloud-mcp] Services: Email, Calendar, Contacts, Reminders, Notes, Messages, Safari');
+} else {
+  console.error('[icloud-mcp] Services: Email, Calendar, Contacts');
+  console.error(`[icloud-mcp] Credentials configured: ${!!(config.ICLOUD_EMAIL && config.ICLOUD_APP_PASSWORD)}`);
+}
+
+if (config.USE_TEST_MODE) {
+  console.error('[icloud-mcp] TEST MODE ENABLED');
+}
+
+// serveStdio returns a handle (not a promise); it owns the transport lifetime.
+const handle = serveStdio(buildServer);
+
+function shutdown(signal) {
+  console.error(`[icloud-mcp] Received ${signal}, shutting down`);
+  Promise.resolve(handle?.close?.())
+    .catch(() => {})
+    .finally(() => process.exit(0));
+}
+
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));

package/messages/index.js

@@ -0,0 +1,157 @@
+/**
+ * Messages Module
+ * MCP tool definitions for Messages.app
+ * Send via AppleScript, read via imsg CLI
+ */
+
+const { z } = require('zod');
+const localClient = require('./local-client');
+const { formatError, formatSuccess, withErrorHandler } = require('../utils/error-handler');
+const { listOutput, listResult } = require('../utils/schemas');
+const { isLocalMode } = require('../mode');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+// Homebrew's prefix differs between Apple Silicon and Intel, and an MCP server
+// launched by a GUI client often has a minimal PATH, so probe both.
+const IMSG_CANDIDATES = [
+  process.env.ICLOUD_MCP_IMSG_PATH,
+  process.env.IMSG_PATH,
+  '/opt/homebrew/bin/imsg',
+  '/usr/local/bin/imsg'
+].filter(Boolean);
+
+function resolveImsg() {
+  for (const candidate of IMSG_CANDIDATES) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  // Last resort: let the OS search PATH.
+  return 'imsg';
+}
+
+function requireLocalMode(toolName) {
+  if (!isLocalMode()) {
+    return formatError(new Error(`${toolName} is only available in LOCAL mode. Use set-mode to switch.`));
+  }
+  return null;
+}
+
+function runImsg(args) {
+  let output;
+  try {
+    output = execFileSync(resolveImsg(), args, {
+      timeout: 15000,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+  } catch (error) {
+    const detail = (error.stderr || error.message || '').toString();
+    if (detail.includes('permissionDenied')) {
+      throw new Error('Full Disk Access required. Grant it to the terminal in System Settings > Privacy & Security > Full Disk Access.');
+    }
+    if (error.code === 'ENOENT') {
+      throw new Error('The imsg CLI was not found. Install it (brew install imsg) or set ICLOUD_MCP_IMSG_PATH.');
+    }
+    throw new Error(detail.trim() || 'imsg failed');
+  }
+
+  try {
+    return JSON.parse(output);
+  } catch {
+    // imsg outputs JSONL (one JSON object per line)
+    const lines = output.trim().split('\n').filter(Boolean);
+    const parsed = lines.map(l => { try { return JSON.parse(l); } catch { return { raw: l }; } });
+    return parsed.length === 1 ? parsed[0] : parsed;
+  }
+}
+
+const messagesTools = [
+  {
+    name: 'list-chats',
+    outputSchema: listOutput('Recent conversations'),
+    title: 'List Chats',
+    description: 'List recent iMessage/SMS conversations with contact names and last message preview',
+    inputSchema: {
+      limit: z.number().int().min(1).max(200).optional().describe('Number of conversations to show (default 20)')
+    },
+    annotations: {"readOnlyHint":true,"idempotentHint":true,"openWorldHint":false},
+    handler: withErrorHandler(async ({ limit = 20 }) => {
+      const modeError = requireLocalMode('list-chats');
+      if (modeError) return modeError;
+      const result = runImsg(['chats', '--limit', String(limit), '--json']);
+      // imsg emits JSONL, and runImsg unwraps a single line to a bare object.
+      const chats = Array.isArray(result) ? result : (result ? [result] : []);
+      return formatSuccess(JSON.stringify(chats, null, 2), listResult(chats));
+    }, 'list-chats')
+  },
+  {
+    name: 'read-messages',
+    title: 'Read Messages',
+    description: 'Read message history for a specific iMessage/SMS conversation',
+    inputSchema: {
+      chatId: z.number().int().describe('Chat ID (rowid from list-chats)'),
+      limit: z.number().int().min(1).max(500).optional().describe('Number of messages (default 20)'),
+      start: z.string().optional().describe('Start date (ISO 8601, optional)'),
+      end: z.string().optional().describe('End date (ISO 8601, optional)'),
+      attachments: z.boolean().optional().describe('Include attachment info (default false)')
+    },
+    annotations: {"readOnlyHint":true,"idempotentHint":true,"openWorldHint":false},
+    handler: withErrorHandler(async ({ chatId, limit = 20, start, end, attachments }) => {
+      const modeError = requireLocalMode('read-messages');
+      if (modeError) return modeError;
+      const args = ['history', '--chat-id', String(chatId), '--limit', String(limit), '--json'];
+      if (start) args.push('--start', start);
+      if (end) args.push('--end', end);
+      if (attachments) args.push('--attachments');
+      const result = runImsg(args);
+      return formatSuccess(JSON.stringify(result, null, 2));
+    }, 'read-messages')
+  },
+  {
+    name: 'send-message',
+    title: 'Send Message',
+    description: 'Send an iMessage or SMS. IMPORTANT: Always confirm with user before sending.',
+    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},
+    handler: withErrorHandler(async ({ to, body, file }) => {
+      const modeError = requireLocalMode('send-message');
+      if (modeError) return modeError;
+      try {
+        const result = await localClient.sendMessage({ to, body });
+        return formatSuccess(JSON.stringify(result, null, 2));
+      } catch (error) {
+        // Fallback to imsg CLI
+        try {
+          const args = ['send', '--to', to, '--text', body];
+          if (file) args.push('--file', file);
+          const result = runImsg(args);
+          return formatSuccess(JSON.stringify(result, null, 2));
+        } catch (e) {
+          throw new Error(`${error.message} (imsg fallback also failed: ${e.message})`);
+        }
+      }
+    }, 'send-message')
+  },
+  {
+    name: 'react-message',
+    title: 'React To Message',
+    description: 'Send a tapback reaction (love, like, dislike, laugh, emphasis, question)',
+    inputSchema: {
+      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},
+    handler: withErrorHandler(async ({ chatId, type }) => {
+      const modeError = requireLocalMode('react-message');
+      if (modeError) return modeError;
+      const result = runImsg(['react', '--chat-id', String(chatId), '--type', type]);
+      return formatSuccess(JSON.stringify(result, null, 2));
+    }, 'react-message')
+  }
+];
+
+module.exports = { messagesTools };

package/messages/local-client.js

@@ -0,0 +1,74 @@
+/**
+ * Local Messages Client
+ * Accesses Messages.app via AppleScript
+ * Note: Messages.app has limited AppleScript support - can only send, not read
+ */
+
+const { runAppleScript, escapeAppleScript } = require('../utils/applescript');
+
+/**
+ * Send an iMessage or SMS
+ * @param {Object} options - Message options
+ * @returns {Promise<Object>} - Send result
+ */
+async function sendMessage({ to, body }) {
+  // Determine if it's a phone number or email
+  const isPhone = /^[\d\s\-\+\(\)]+$/.test(to.replace(/\s/g, ''));
+
+  const script = `
+    tell application "Messages"
+      set targetService to 1st account whose service type = iMessage
+      set targetBuddy to participant "${escapeAppleScript(to)}" of targetService
+      send "${escapeAppleScript(body)}" to targetBuddy
+    end tell
+    return "sent"
+  `;
+
+  try {
+    await runAppleScript(script);
+    return { success: true, message: `Message sent to ${to}` };
+  } catch (error) {
+    // Try alternative approach for phone numbers
+    if (isPhone) {
+      const altScript = `
+        tell application "Messages"
+          set targetService to 1st account whose service type = iMessage
+          set theBuddy to buddy "${escapeAppleScript(to)}" of targetService
+          send "${escapeAppleScript(body)}" to theBuddy
+        end tell
+        return "sent"
+      `;
+
+      try {
+        await runAppleScript(altScript);
+        return { success: true, message: `Message sent to ${to}` };
+      } catch (e) {
+        throw error;
+      }
+    }
+    throw error;
+  }
+}
+
+/**
+ * Send a message using Shortcuts Events (more reliable)
+ * @param {Object} options - Message options
+ * @returns {Promise<Object>} - Send result
+ */
+async function sendMessageViaShortcuts({ to, body }) {
+  // This method uses "Shortcuts Events" which can be more reliable
+  const script = `
+    tell application "Messages"
+      send "${escapeAppleScript(body)}" to buddy "${escapeAppleScript(to)}" of (1st account whose service type = iMessage)
+    end tell
+    return "sent"
+  `;
+
+  await runAppleScript(script);
+  return { success: true, message: `Message sent to ${to}` };
+}
+
+module.exports = {
+  sendMessage,
+  sendMessageViaShortcuts
+};

package/mode.js

@@ -0,0 +1,82 @@
+/**
+ * Mode management module
+ *
+ * Manages the current operating mode (local vs cloud)
+ * Separate module to avoid circular dependencies
+ */
+
+const config = require('./config');
+
+// Initial mode based on config
+let currentMode = (config.USE_LOCAL_MODE && config.IS_MACOS) ? 'local' : 'cloud';
+
+// Listeners notified after a successful mode change. The server uses this to
+// emit notifications/tools/list_changed, since the mode decides which tools work.
+const listeners = new Set();
+
+/**
+ * Subscribe to mode changes.
+ * @param {() => void} fn
+ * @returns {() => void} - Unsubscribe
+ */
+function onModeChange(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/**
+ * Get current mode
+ * @returns {'local' | 'cloud'}
+ */
+function getMode() {
+  return currentMode;
+}
+
+/**
+ * Set current mode
+ * @param {'local' | 'cloud'} mode
+ */
+function setMode(mode) {
+  if (mode !== 'local' && mode !== 'cloud') {
+    throw new Error('Mode must be "local" or "cloud"');
+  }
+
+  if (mode === 'local' && !config.IS_MACOS) {
+    throw new Error('Local mode only available on macOS');
+  }
+
+  currentMode = mode;
+  console.error(`[icloud-mcp] Mode changed to: ${mode}`);
+
+  for (const fn of listeners) {
+    try {
+      fn(mode);
+    } catch (error) {
+      console.error('[icloud-mcp] Mode listener failed:', error.message);
+    }
+  }
+}
+
+/**
+ * Check if currently in local mode
+ * @returns {boolean}
+ */
+function isLocalMode() {
+  return currentMode === 'local';
+}
+
+/**
+ * Check if currently in cloud mode
+ * @returns {boolean}
+ */
+function isCloudMode() {
+  return currentMode === 'cloud';
+}
+
+module.exports = {
+  getMode,
+  setMode,
+  isLocalMode,
+  isCloudMode,
+  onModeChange
+};

package/notes/index.js

@@ -0,0 +1,162 @@
+/**
+ * Notes Module
+ * MCP tool definitions for Notes.app
+ * NOTE: Only available in LOCAL mode (AppleScript)
+ */
+
+const { z } = require('zod');
+const localClient = require('./local-client');
+const { formatError } = require('../utils/error-handler');
+const { listOutput, listResult } = require('../utils/schemas');
+const { isLocalMode } = require('../mode');
+
+function requireLocalMode(toolName) {
+  if (!isLocalMode()) {
+    return formatError(new Error(`${toolName} is only available in LOCAL mode. Use set-mode to switch.`));
+  }
+  return null;
+}
+
+const notesTools = [
+  {
+    name: 'list-note-folders',
+    outputSchema: listOutput('list-note-folders'),
+    title: 'List Note Folders',
+    description: 'Lists all folders in Notes.app (LOCAL mode only)',
+    inputSchema: {},
+    annotations: {"readOnlyHint":true,"idempotentHint":true,"openWorldHint":false},
+    handler: async () => {
+      const modeError = requireLocalMode('list-note-folders');
+      if (modeError) return modeError;
+
+      try {
+        const folders = await localClient.listNoteFolders();
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(folders, null, 2)
+          }],
+          structuredContent: listResult(folders)
+        };
+      } catch (error) {
+        return formatError(error, 'list-note-folders');
+      }
+    }
+  },
+  {
+    name: 'list-notes',
+    outputSchema: listOutput('list-notes'),
+    title: 'List Notes',
+    description: 'Lists notes from a specific folder or all folders',
+    inputSchema: {
+      folderName: z.string().optional().describe('Name of the folder (optional, lists all if not provided)'),
+      count: z.number().int().min(1).max(200).optional().describe('Maximum number of notes to return (default: 25)')
+    },
+    annotations: {"readOnlyHint":true,"idempotentHint":true,"openWorldHint":false},
+    handler: async ({ folderName, count = 25 }) => {
+      const modeError = requireLocalMode('list-notes');
+      if (modeError) return modeError;
+
+      try {
+        const notes = await localClient.listNotes(folderName, count);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(notes, null, 2)
+          }],
+          structuredContent: listResult(notes)
+        };
+      } catch (error) {
+        return formatError(error, 'list-notes');
+      }
+    }
+  },
+  {
+    name: 'read-note',
+    title: 'Read Note',
+    description: 'Reads the content of a specific note',
+    inputSchema: {
+      noteId: z.string().describe('ID of the note to read (required)')
+    },
+    annotations: {"readOnlyHint":true,"idempotentHint":true,"openWorldHint":false},
+    handler: async ({ noteId }) => {
+      const modeError = requireLocalMode('read-note');
+      if (modeError) return modeError;
+
+      try {
+        const note = await localClient.readNote(noteId);
+        if (!note) {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({ error: 'Note not found' })
+            }]
+          };
+        }
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(note, null, 2)
+          }]
+        };
+      } catch (error) {
+        return formatError(error, 'read-note');
+      }
+    }
+  },
+  {
+    name: 'create-note',
+    title: 'Create Note',
+    description: 'Creates a new note',
+    inputSchema: {
+      title: z.string().describe('Note title (required)'),
+      body: z.string().optional().describe('Note content/body'),
+      folderName: z.string().optional().describe('Folder to create the note in (default: Notes)')
+    },
+    annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
+    handler: async (args) => {
+      const modeError = requireLocalMode('create-note');
+      if (modeError) return modeError;
+
+      try {
+        const result = await localClient.createNote(args);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+          }]
+        };
+      } catch (error) {
+        return formatError(error, 'create-note');
+      }
+    }
+  },
+  {
+    name: 'search-notes',
+    title: 'Search Notes',
+    description: 'Search notes by text in title or content',
+    inputSchema: {
+      query: z.string().describe('Search text (required)'),
+      count: z.number().int().min(1).max(200).optional().describe('Maximum results to return (default: 25)')
+    },
+    annotations: {"readOnlyHint":true,"idempotentHint":true,"openWorldHint":false},
+    handler: async ({ query, count = 25 }) => {
+      const modeError = requireLocalMode('search-notes');
+      if (modeError) return modeError;
+
+      try {
+        const results = await localClient.searchNotes(query, count);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(results, null, 2)
+          }]
+        };
+      } catch (error) {
+        return formatError(error, 'search-notes');
+      }
+    }
+  }
+];
+
+module.exports = { notesTools };