Apple MCP

Instructions

Implementation Reference

• index.ts:443-671 (handler)

  Main execution handler for the 'mail' MCP tool. Loads utils/mail module and handles operations: unread (getUnreadMails), search (searchMails), send (sendMail), mailboxes/accounts (getMailboxes etc.). Includes custom AppleScript for account-specific unread emails.

          case "mail": {
            if (!isMailArgs(args)) {
              throw new Error("Invalid arguments for mail tool");
            }
  
            try {
              const mailModule = await loadModule('mail');
              
              switch (args.operation) {
                case "unread": {
                  // If an account is specified, we'll try to search specifically in that account
                  let emails;
                  if (args.account) {
                    console.error(`Getting unread emails for account: ${args.account}`);
                    // Use AppleScript to get unread emails from specific account
                    const script = `
  tell application "Mail"
      set resultList to {}
      try
          set targetAccount to first account whose name is "${args.account.replace(/"/g, '\\"')}"
          
          -- Get mailboxes for this account
          set acctMailboxes to every mailbox of targetAccount
          
          -- If mailbox is specified, only search in that mailbox
          set mailboxesToSearch to acctMailboxes
          ${args.mailbox ? `
          set mailboxesToSearch to {}
          repeat with mb in acctMailboxes
              if name of mb is "${args.mailbox.replace(/"/g, '\\"')}" then
                  set mailboxesToSearch to {mb}
                  exit repeat
              end if
          end repeat
          ` : ''}
          
          -- Search specified mailboxes
          repeat with mb in mailboxesToSearch
              try
                  set unreadMessages to (messages of mb whose read status is false)
                  if (count of unreadMessages) > 0 then
                      set msgLimit to ${args.limit || 10}
                      if (count of unreadMessages) < msgLimit then
                          set msgLimit to (count of unreadMessages)
                      end if
                      
                      repeat with i from 1 to msgLimit
                          try
                              set currentMsg to item i of unreadMessages
                              set msgData to {subject:(subject of currentMsg), sender:(sender of currentMsg), ¬
                                          date:(date sent of currentMsg) as string, mailbox:(name of mb)}
                              
                              -- Try to get content if possible
                              try
                                  set msgContent to content of currentMsg
                                  if length of msgContent > 500 then
                                      set msgContent to (text 1 thru 500 of msgContent) & "..."
                                  end if
                                  set msgData to msgData & {content:msgContent}
                              on error
                                  set msgData to msgData & {content:"[Content not available]"}
                              end try
                              
                              set end of resultList to msgData
                          on error
                              -- Skip problematic messages
                          end try
                      end repeat
                      
                      if (count of resultList) ≥ ${args.limit || 10} then exit repeat
                  end if
              on error
                  -- Skip problematic mailboxes
              end try
          end repeat
      on error errMsg
          return "Error: " & errMsg
      end try
      
      return resultList
  end tell`;
                    
                    try {
                      const asResult = await runAppleScript(script);
                      if (asResult && asResult.startsWith('Error:')) {
                        throw new Error(asResult);
                      }
                      
                      // Parse the results - similar to general getUnreadMails
                      const emailData = [];
                      const matches = asResult.match(/\{([^}]+)\}/g);
                      if (matches && matches.length > 0) {
                        for (const match of matches) {
                          try {
                            const props = match.substring(1, match.length - 1).split(',');
                            const email: any = {};
                            
                            props.forEach(prop => {
                              const parts = prop.split(':');
                              if (parts.length >= 2) {
                                const key = parts[0].trim();
                                const value = parts.slice(1).join(':').trim();
                                email[key] = value;
                              }
                            });
                            
                            if (email.subject || email.sender) {
                              emailData.push({
                                subject: email.subject || "No subject",
                                sender: email.sender || "Unknown sender",
                                dateSent: email.date || new Date().toString(),
                                content: email.content || "[Content not available]",
                                isRead: false,
                                mailbox: `${args.account} - ${email.mailbox || "Unknown"}`
                              });
                            }
                          } catch (parseError) {
                            console.error('Error parsing email match:', parseError);
                          }
                        }
                      }
                      
                      emails = emailData;
                    } catch (error) {
                      console.error('Error getting account-specific emails:', error);
                      // Fallback to general method if specific account fails
                      emails = await mailModule.getUnreadMails(args.limit);
                    }
                  } else {
                    // No account specified, use the general method
                    emails = await mailModule.getUnreadMails(args.limit);
                  }
                  
                  return {
                    content: [{ 
                      type: "text", 
                      text: emails.length > 0 ? 
                        `Found ${emails.length} unread email(s)${args.account ? ` in account "${args.account}"` : ''}${args.mailbox ? ` and mailbox "${args.mailbox}"` : ''}:\n\n` +
                        emails.map((email: any) => 
                          `[${email.dateSent}] From: ${email.sender}\nMailbox: ${email.mailbox}\nSubject: ${email.subject}\n${email.content.substring(0, 500)}${email.content.length > 500 ? '...' : ''}`
                        ).join("\n\n") :
                        `No unread emails found${args.account ? ` in account "${args.account}"` : ''}${args.mailbox ? ` and mailbox "${args.mailbox}"` : ''}`
                    }],
                    isError: false
                  };
                }
  
                case "search": {
                  if (!args.searchTerm) {
                    throw new Error("Search term is required for search operation");
                  }
                  const emails = await mailModule.searchMails(args.searchTerm, args.limit);
                  return {
                    content: [{ 
                      type: "text", 
                      text: emails.length > 0 ? 
                        `Found ${emails.length} email(s) for "${args.searchTerm}"${args.account ? ` in account "${args.account}"` : ''}${args.mailbox ? ` and mailbox "${args.mailbox}"` : ''}:\n\n` +
                        emails.map((email: any) => 
                          `[${email.dateSent}] From: ${email.sender}\nMailbox: ${email.mailbox}\nSubject: ${email.subject}\n${email.content.substring(0, 200)}${email.content.length > 200 ? '...' : ''}`
                        ).join("\n\n") :
                        `No emails found for "${args.searchTerm}"${args.account ? ` in account "${args.account}"` : ''}${args.mailbox ? ` and mailbox "${args.mailbox}"` : ''}`
                    }],
                    isError: false
                  };
                }
  
                case "send": {
                  if (!args.to || !args.subject || !args.body) {
                    throw new Error("Recipient (to), subject, and body are required for send operation");
                  }
                  const result = await mailModule.sendMail(args.to, args.subject, args.body, args.cc, args.bcc);
                  return {
                    content: [{ type: "text", text: result }],
                    isError: false
                  };
                }
  
                case "mailboxes": {
                  if (args.account) {
                    const mailboxes = await mailModule.getMailboxesForAccount(args.account);
                    return {
                      content: [{ 
                        type: "text", 
                        text: mailboxes.length > 0 ? 
                          `Found ${mailboxes.length} mailboxes for account "${args.account}":\n\n${mailboxes.join("\n")}` :
                          `No mailboxes found for account "${args.account}". Make sure the account name is correct.`
                      }],
                      isError: false
                    };
                  } else {
                    const mailboxes = await mailModule.getMailboxes();
                    return {
                      content: [{ 
                        type: "text", 
                        text: mailboxes.length > 0 ? 
                          `Found ${mailboxes.length} mailboxes:\n\n${mailboxes.join("\n")}` :
                          "No mailboxes found. Make sure Mail app is running and properly configured."
                      }],
                      isError: false
                    };
                  }
                }
  
                case "accounts": {
                  const accounts = await mailModule.getAccounts();
                  return {
                    content: [{ 
                      type: "text", 
                      text: accounts.length > 0 ? 
                        `Found ${accounts.length} email accounts:\n\n${accounts.join("\n")}` :
                        "No email accounts found. Make sure Mail app is configured with at least one account."
                    }],
                    isError: false
                  };
                }
  
                default:
                  throw new Error(`Unknown operation: ${args.operation}`);
              }
            } catch (error) {
              return {
                content: [{
                  type: "text",
                  text: `Error with mail operation: ${error instanceof Error ? error.message : String(error)}`
                }],
                isError: true
              };
            }
          }

• tools.ts:81-131 (schema)

  Input schema and metadata for the 'mail' tool, defining parameters and operations.

  const MAIL_TOOL: Tool = {
    name: "mail",
    description: "Interact with Apple Mail app - read unread emails, search emails, and send emails",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          description: "Operation to perform: 'unread', 'search', 'send', 'mailboxes', or 'accounts'",
          enum: ["unread", "search", "send", "mailboxes", "accounts"]
        },
        account: {
          type: "string",
          description: "Email account to use (optional - if not provided, searches across all accounts)"
        },
        mailbox: {
          type: "string",
          description: "Mailbox to use (optional - if not provided, uses inbox or searches across all mailboxes)"
        },
        limit: {
          type: "number",
          description: "Number of emails to retrieve (optional, for unread and search operations)"
        },
        searchTerm: {
          type: "string",
          description: "Text to search for in emails (required for search operation)"
        },
        to: {
          type: "string",
          description: "Recipient email address (required for send operation)"
        },
        subject: {
          type: "string",
          description: "Email subject (required for send operation)"
        },
        body: {
          type: "string",
          description: "Email body content (required for send operation)"
        },
        cc: {
          type: "string",
          description: "CC email address (optional for send operation)"
        },
        bcc: {
          type: "string",
          description: "BCC email address (optional for send operation)"
        }
      },
      required: ["operation"]
    }
  };

• tools.ts:307-309 (registration)

  Registers the MAIL_TOOL in the exported tools array for MCP server list tools response.

  const tools = [CONTACTS_TOOL, NOTES_TOOL, MESSAGES_TOOL, MAIL_TOOL, REMINDERS_TOOL, WEB_SEARCH_TOOL, CALENDAR_TOOL, MAPS_TOOL];

• utils/mail.ts:748-755 (helper)

  Default export of mail helper functions invoked by the 'mail' tool handler.

  export default {
    getUnreadMails,
    searchMails,
    sendMail,
    getMailboxes,
    getAccounts,
    getMailboxesForAccount,
  };

• index.ts:1178-1223 (schema)

  Runtime input argument validation for 'mail' tool calls, enforcing schema constraints.

  function isMailArgs(args: unknown): args is {
    operation: "unread" | "search" | "send" | "mailboxes" | "accounts";
    account?: string;
    mailbox?: string;
    limit?: number;
    searchTerm?: string;
    to?: string;
    subject?: string;
    body?: string;
    cc?: string;
    bcc?: string;
  } {
    if (typeof args !== "object" || args === null) return false;
    
    const { operation, account, mailbox, limit, searchTerm, to, subject, body, cc, bcc } = args as any;
    
    if (!operation || !["unread", "search", "send", "mailboxes", "accounts"].includes(operation)) {
      return false;
    }
    
    // Validate required fields based on operation
    switch (operation) {
      case "search":
        if (!searchTerm || typeof searchTerm !== "string") return false;
        break;
      case "send":
        if (!to || typeof to !== "string" || 
            !subject || typeof subject !== "string" || 
            !body || typeof body !== "string") return false;
        break;
      case "unread":
      case "mailboxes":
      case "accounts":
        // No additional required fields
        break;
    }
    
    // Validate field types if present
    if (account && typeof account !== "string") return false;
    if (mailbox && typeof mailbox !== "string") return false;
    if (limit && typeof limit !== "number") return false;
    if (cc && typeof cc !== "string") return false;
    if (bcc && typeof bcc !== "string") return false;
    
    return true;
  }