Apple MCP

by jxnl

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

messages

Send, read, schedule, and check unread messages in the Apple Messages app through the MCP server.

Instructions

Interact with Apple Messages app - send, read, schedule messages and check unread messages

Input Schema

TableJSON Schema

Name	Required	Description
`operation`	Yes	Operation to perform: 'send', 'read', 'schedule', or 'unread'
`phoneNumber`	No	Phone number to send message to (required for send, read, and schedule operations)
`message`	No	Message to send (required for send and schedule operations)
`limit`	No	Number of messages to read (optional, for read and unread operations)
`scheduledTime`	No	ISO string of when to send the message (required for schedule operation)

Implementation Reference

tools.ts:49-79 (schema)

Defines the MCP Tool schema for the 'messages' tool, including input validation for operations: send, read, schedule, unread.

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)

Registers the 'messages' tool (MESSAGES_TOOL) in the array of tools exported for use in the MCP server.

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:62-71 (helper)

Helper function to send a message via Apple Messages app using AppleScript.

async function sendMessage(phoneNumber: string, message: string) {
    const escapedMessage = message.replace(/"/g, '\\"');
    const result = await runAppleScript(`
tell application "Messages"
    set targetService to 1st service whose service type = iMessage
    set targetBuddy to buddy "${phoneNumber}"
    send "${escapedMessage}" to targetBuddy
end tell`);
    return result;
}

utils/message.ts:213-341 (helper)

Helper function to read recent messages from a specific phone number by querying the Messages chat.db SQLite database.

async function readMessages(phoneNumber: string, limit: number = 10): Promise<Message[]> {
    try {
        // Check database access with retries
        const hasAccess = await retryOperation(checkMessagesDBAccess);
        if (!hasAccess) {
            return [];
        }

        // Get all possible formats of the phone number
        const phoneFormats = normalizePhoneNumber(phoneNumber);
        console.error("Trying phone formats:", phoneFormats);
        
        // Create SQL IN clause with all phone number formats
        const phoneList = phoneFormats.map(p => `'${p.replace(/'/g, "''")}'`).join(',');
        
        const query = `
            SELECT 
                m.ROWID as message_id,
                CASE 
                    WHEN m.text IS NOT NULL AND m.text != '' THEN m.text
                    WHEN m.attributedBody IS NOT NULL THEN hex(m.attributedBody)
                    ELSE NULL
                END as content,
                datetime(m.date/1000000000 + strftime('%s', '2001-01-01'), 'unixepoch', 'localtime') as date,
                h.id as sender,
                m.is_from_me,
                m.is_audio_message,
                m.cache_has_attachments,
                m.subject,
                CASE 
                    WHEN m.text IS NOT NULL AND m.text != '' THEN 0
                    WHEN m.attributedBody IS NOT NULL THEN 1
                    ELSE 2
                END as content_type
            FROM message m 
            INNER JOIN handle h ON h.ROWID = m.handle_id 
            WHERE h.id IN (${phoneList})
                AND (m.text IS NOT NULL OR m.attributedBody IS NOT NULL OR m.cache_has_attachments = 1)
                AND m.is_from_me IS NOT NULL  -- Ensure it's a real message
                AND m.item_type = 0  -- Regular messages only
                AND m.is_audio_message = 0  -- Skip audio messages
            ORDER BY m.date DESC 
            LIMIT ${limit}
        `;

        // Execute query with retries
        const { stdout } = await retryOperation(() => 
            execAsync(`sqlite3 -json "${process.env.HOME}/Library/Messages/chat.db" "${query}"`)
        );
        
        if (!stdout.trim()) {
            console.error("No messages found in database for the given phone number");
            return [];
        }

        const messages = JSON.parse(stdout) as (Message & {
            message_id: number;
            is_audio_message: number;
            cache_has_attachments: number;
            subject: string | null;
            content_type: number;
        })[];

        // Process messages with potential parallel attachment fetching
        const processedMessages = await Promise.all(
            messages
                .filter(msg => msg.content !== null || msg.cache_has_attachments === 1)
                .map(async msg => {
                    let content = msg.content || '';
                    let url: string | undefined;
                    
                    // If it's an attributedBody (content_type = 1), decode it
                    if (msg.content_type === 1) {
                        const decoded = decodeAttributedBody(content);
                        content = decoded.text;
                        url = decoded.url;
                    } else {
                        // Check for URLs in regular text messages
                        const urlMatch = content.match(/(https?:\/\/[^\s]+)/);
                        if (urlMatch) {
                            url = urlMatch[1];
                        }
                    }
                    
                    // Get attachments if any
                    let attachments: string[] = [];
                    if (msg.cache_has_attachments) {
                        attachments = await getAttachmentPaths(msg.message_id);
                    }
                    
                    // Add subject if present
                    if (msg.subject) {
                        content = `Subject: ${msg.subject}\n${content}`;
                    }
                    
                    // Format the message object
                    const formattedMsg: Message = {
                        content: content || '[No text content]',
                        date: new Date(msg.date).toISOString(),
                        sender: msg.sender,
                        is_from_me: Boolean(msg.is_from_me)
                    };

                    // Add attachments if any
                    if (attachments.length > 0) {
                        formattedMsg.attachments = attachments;
                        formattedMsg.content += '\n[Attachments: ' + attachments.length + ']';
                    }

                    // Add URL if present
                    if (url) {
                        formattedMsg.url = url;
                        formattedMsg.content += '\n[URL: ' + url + ']';
                    }

                    return formattedMsg;
                })
        );

        return processedMessages;
    } catch (error) {
        console.error('Error reading messages:', error);
        if (error instanceof Error) {
            console.error('Error details:', error.message);
            console.error('Stack trace:', error.stack);
        }
        return [];
    }
}

utils/message.ts:343-464 (helper)

Helper function to retrieve unread incoming messages from the Messages database.

async function getUnreadMessages(limit: number = 10): Promise<Message[]> {
    try {
        // Check database access with retries
        const hasAccess = await retryOperation(checkMessagesDBAccess);
        if (!hasAccess) {
            return [];
        }

        const query = `
            SELECT 
                m.ROWID as message_id,
                CASE 
                    WHEN m.text IS NOT NULL AND m.text != '' THEN m.text
                    WHEN m.attributedBody IS NOT NULL THEN hex(m.attributedBody)
                    ELSE NULL
                END as content,
                datetime(m.date/1000000000 + strftime('%s', '2001-01-01'), 'unixepoch', 'localtime') as date,
                h.id as sender,
                m.is_from_me,
                m.is_audio_message,
                m.cache_has_attachments,
                m.subject,
                CASE 
                    WHEN m.text IS NOT NULL AND m.text != '' THEN 0
                    WHEN m.attributedBody IS NOT NULL THEN 1
                    ELSE 2
                END as content_type
            FROM message m 
            INNER JOIN handle h ON h.ROWID = m.handle_id 
            WHERE m.is_from_me = 0  -- Only messages from others
                AND m.is_read = 0   -- Only unread messages
                AND (m.text IS NOT NULL OR m.attributedBody IS NOT NULL OR m.cache_has_attachments = 1)
                AND m.is_audio_message = 0  -- Skip audio messages
                AND m.item_type = 0  -- Regular messages only
            ORDER BY m.date DESC 
            LIMIT ${limit}
        `;

        // Execute query with retries
        const { stdout } = await retryOperation(() => 
            execAsync(`sqlite3 -json "${process.env.HOME}/Library/Messages/chat.db" "${query}"`)
        );
        
        if (!stdout.trim()) {
            console.error("No unread messages found");
            return [];
        }

        const messages = JSON.parse(stdout) as (Message & {
            message_id: number;
            is_audio_message: number;
            cache_has_attachments: number;
            subject: string | null;
            content_type: number;
        })[];

        // Process messages with potential parallel attachment fetching
        const processedMessages = await Promise.all(
            messages
                .filter(msg => msg.content !== null || msg.cache_has_attachments === 1)
                .map(async msg => {
                    let content = msg.content || '';
                    let url: string | undefined;
                    
                    // If it's an attributedBody (content_type = 1), decode it
                    if (msg.content_type === 1) {
                        const decoded = decodeAttributedBody(content);
                        content = decoded.text;
                        url = decoded.url;
                    } else {
                        // Check for URLs in regular text messages
                        const urlMatch = content.match(/(https?:\/\/[^\s]+)/);
                        if (urlMatch) {
                            url = urlMatch[1];
                        }
                    }
                    
                    // Get attachments if any
                    let attachments: string[] = [];
                    if (msg.cache_has_attachments) {
                        attachments = await getAttachmentPaths(msg.message_id);
                    }
                    
                    // Add subject if present
                    if (msg.subject) {
                        content = `Subject: ${msg.subject}\n${content}`;
                    }
                    
                    // Format the message object
                    const formattedMsg: Message = {
                        content: content || '[No text content]',
                        date: new Date(msg.date).toISOString(),
                        sender: msg.sender,
                        is_from_me: Boolean(msg.is_from_me)
                    };

                    // Add attachments if any
                    if (attachments.length > 0) {
                        formattedMsg.attachments = attachments;
                        formattedMsg.content += '\n[Attachments: ' + attachments.length + ']';
                    }

                    // Add URL if present
                    if (url) {
                        formattedMsg.url = url;
                        formattedMsg.content += '\n[URL: ' + url + ']';
                    }

                    return formattedMsg;
                })
        );

        return processedMessages;
    } catch (error) {
        console.error('Error reading unread messages:', error);
        if (error instanceof Error) {
            console.error('Error details:', error.message);
            console.error('Stack trace:', error.stack);
        }
        return [];
    }
}

utils/message.ts:466-501 (helper)

Helper function to schedule a message to be sent at a future time, plus the export of all message-related functions.

async function scheduleMessage(phoneNumber: string, message: string, scheduledTime: Date) {
    // Store the scheduled message details
    const scheduledMessages = new Map();
    
    // Calculate delay in milliseconds
    const delay = scheduledTime.getTime() - Date.now();
    
    if (delay < 0) {
        throw new Error('Cannot schedule message in the past');
    }
    
    // Schedule the message
    const timeoutId = setTimeout(async () => {
        try {
            await sendMessage(phoneNumber, message);
            scheduledMessages.delete(timeoutId);
        } catch (error) {
            console.error('Failed to send scheduled message:', error);
        }
    }, delay);
    
    // Store the scheduled message details for reference
    scheduledMessages.set(timeoutId, {
        phoneNumber,
        message,
        scheduledTime,
        timeoutId
    });
    
    return {
        id: timeoutId,
        scheduledTime,
        message,
        phoneNumber
    };
}

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 18, 2025

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions operations like 'send' and 'schedule,' which imply mutations, but doesn't state whether these require user confirmation, have rate limits, or affect device state. For a tool with multiple operations including writes, this is inadequate, as it omits critical behavioral traits like safety or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, stating the core purpose in a single sentence. It efficiently lists the four operations without unnecessary details. However, it could be slightly more structured by grouping related operations or adding brief context, but overall, it avoids waste and is appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity with 5 parameters, multiple operations including mutations, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects, usage contexts, or return values, leaving gaps that could hinder an AI agent's ability to invoke the tool correctly. For a multi-operation tool with no structured safety hints, more detail is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds minimal meaning beyond the input schema, which has 100% coverage. It implies that parameters are tied to specific operations (e.g., 'message' for 'send'), but doesn't elaborate on semantics like format constraints or dependencies. Since the schema descriptions are comprehensive, the baseline score of 3 is appropriate, as the description doesn't significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Interact with Apple Messages app - send, read, schedule messages and check unread messages.' It specifies the verb ('interact with') and resource ('Apple Messages app'), and lists the four operations. However, it doesn't explicitly differentiate from sibling tools like 'contacts' or 'mail,' which could have overlapping communication functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It lists operations but doesn't specify contexts, prerequisites, or exclusions. For example, it doesn't mention if 'schedule' requires specific permissions or if 'read' is limited to recent messages. With sibling tools like 'calendar' and 'reminders' that might handle scheduling, this lack of differentiation is a significant gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server