Apple MCP

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• index.ts:337-441 (handler)

  Primary handler for the 'messages' tool within the MCP CallToolRequestSchema. Validates arguments using isMessagesArgs, loads utils/message module dynamically, and dispatches to sendMessage, readMessages, scheduleMessage, or getUnreadMessages based on operation. Formats and returns results.
  case "messages": { if (!isMessagesArgs(args)) { throw new Error("Invalid arguments for messages tool"); } try { const messageModule = await loadModule('message'); switch (args.operation) { case "send": { if (!args.phoneNumber || !args.message) { throw new Error("Phone number and message are required for send operation"); } await messageModule.sendMessage(args.phoneNumber, args.message); return { content: [{ type: "text", text: `Message sent to ${args.phoneNumber}` }], isError: false }; } case "read": { if (!args.phoneNumber) { throw new Error("Phone number is required for read operation"); } const messages = await messageModule.readMessages(args.phoneNumber, args.limit); return { content: [{ type: "text", text: messages.length > 0 ? messages.map(msg => `[${new Date(msg.date).toLocaleString()}] ${msg.is_from_me ? 'Me' : msg.sender}: ${msg.content}` ).join("\n") : "No messages found" }], isError: false }; } case "schedule": { if (!args.phoneNumber || !args.message || !args.scheduledTime) { throw new Error("Phone number, message, and scheduled time are required for schedule operation"); } const scheduledMsg = await messageModule.scheduleMessage( args.phoneNumber, args.message, new Date(args.scheduledTime) ); return { content: [{ type: "text", text: `Message scheduled to be sent to ${args.phoneNumber} at ${scheduledMsg.scheduledTime}` }], isError: false }; } case "unread": { const messages = await messageModule.getUnreadMessages(args.limit); // Look up contact names for all messages const contactsModule = await loadModule('contacts'); const messagesWithNames = await Promise.all( messages.map(async msg => { // Only look up names for messages not from me if (!msg.is_from_me) { const contactName = await contactsModule.findContactByPhone(msg.sender); return { ...msg, displayName: contactName || msg.sender // Use contact name if found, otherwise use phone/email }; } return { ...msg, displayName: 'Me' }; }) ); return { content: [{ type: "text", text: messagesWithNames.length > 0 ? `Found ${messagesWithNames.length} unread message(s):\n` + messagesWithNames.map(msg => `[${new Date(msg.date).toLocaleString()}] From ${msg.displayName}:\n${msg.content}` ).join("\n\n") : "No unread messages found" }], isError: false }; } default: throw new Error(`Unknown operation: ${args.operation}`); } } catch (error) { return { content: [{ type: "text", text: `Error with messages operation: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } }
• tools.ts:49-79 (schema)

  Tool schema definition including name, description, and detailed inputSchema with properties and enums for operations.
  const MESSAGES_TOOL: Tool = { name: "messages", description: "Interact with Apple Messages app - send, read, schedule messages and check unread messages", inputSchema: { type: "object", properties: { operation: { type: "string", description: "Operation to perform: 'send', 'read', 'schedule', or 'unread'", enum: ["send", "read", "schedule", "unread"] }, phoneNumber: { type: "string", description: "Phone number to send message to (required for send, read, and schedule operations)" }, message: { type: "string", description: "Message to send (required for send and schedule operations)" }, limit: { type: "number", description: "Number of messages to read (optional, for read and unread operations)" }, scheduledTime: { type: "string", description: "ISO string of when to send the message (required for schedule operation)" } }, required: ["operation"] } };
• tools.ts:308-310 (registration)

  Registration of the 'messages' tool (MESSAGES_TOOL) in the exported tools array used by the MCP server for listing available tools.
  const tools = [CONTACTS_TOOL, NOTES_TOOL, MESSAGES_TOOL, MAIL_TOOL, REMINDERS_TOOL, WEB_SEARCH_TOOL, CALENDAR_TOOL, MAPS_TOOL]; export default tools;
• utils/message.ts:503-504 (helper)

  Export of helper functions from utils/message.ts used by the messages handler: sendMessage, readMessages, scheduleMessage, getUnreadMessages.
  export default { sendMessage, readMessages, scheduleMessage, getUnreadMessages };
• index.ts:1139-1176 (schema)

  Type guard function for validating input arguments against the messages tool schema before execution.
  function isMessagesArgs(args: unknown): args is { operation: "send" | "read" | "schedule" | "unread"; phoneNumber?: string; message?: string; limit?: number; scheduledTime?: string; } { if (typeof args !== "object" || args === null) return false; const { operation, phoneNumber, message, limit, scheduledTime } = args as any; if (!operation || !["send", "read", "schedule", "unread"].includes(operation)) { return false; } // Validate required fields based on operation switch (operation) { case "send": case "schedule": if (!phoneNumber || !message) return false; if (operation === "schedule" && !scheduledTime) return false; break; case "read": if (!phoneNumber) return false; break; case "unread": // No additional required fields break; } // Validate field types if present if (phoneNumber && typeof phoneNumber !== "string") return false; if (message && typeof message !== "string") return false; if (limit && typeof limit !== "number") return false; if (scheduledTime && typeof scheduledTime !== "string") return false; return true; }