messages_get_messages

Retrieve messages from macOS Messages app using AppleScript integration for LLM applications to access iMessage data.

Instructions

[iMessage operations] Get messages from the Messages app

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of messages to retrieve

Implementation Reference

src/categories/messages.ts:61-116 (handler)

Core implementation of messages_get_messages tool. Defines the 'get_messages' script in messages category, including input schema (limit parameter) and AppleScript generator that directly queries the iMessage SQLite database at ~/Library/Messages/chat.db to retrieve recent messages with sender, text, date, and chat info.

    {
      name: "get_messages",
      description: "Get messages from the Messages app",
      schema: {
        type: "object",
        properties: {
          limit: {
            type: "number",
            description: "Maximum number of messages to retrieve",
            default: 100
          }
        }
      },
      script: (args) => `
 on run
	-- Path to the Messages database
	set dbPath to (do shell script "echo ~/Library/Messages/chat.db")
	
	-- Create a temporary SQL file for our query
	set tempFile to (do shell script "mktemp /tmp/imessage_query.XXXXXX")
	
	-- Write SQL query to temp file
	do shell script "cat > " & quoted form of tempFile & " << 'EOF'
SELECT
    datetime(message.date/1000000000 + strftime('%s', '2001-01-01'), 'unixepoch', 'localtime') as message_date,
    handle.id as sender,
    message.text as message_text,
    chat.display_name as chat_name
FROM
    message
    LEFT JOIN handle ON message.handle_id = handle.ROWID
    LEFT JOIN chat_message_join ON message.ROWID = chat_message_join.message_id
    LEFT JOIN chat ON chat_message_join.chat_id = chat.ROWID
ORDER BY
    message.date DESC
LIMIT ${args.limit};
EOF"
	
	-- Execute the query
	set queryResult to do shell script "sqlite3 " & quoted form of dbPath & " < " & quoted form of tempFile
	
	-- Clean up temp file
	do shell script "rm " & quoted form of tempFile
	
	-- Process and display results
	set resultList to paragraphs of queryResult
	set messageData to {}
	
	repeat with messageLine in resultList
		set messageData to messageData & messageLine
	end repeat
	
	return messageData
end run
      `
    },

src/framework.ts:221-232 (registration)

Dynamic registration of all category scripts as MCP tools in ListToolsRequestSchema handler, constructing tool name as `${category.name}_${script.name}` (e.g. messages_get_messages from messages.get_messages).

this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: this.categories.flatMap((category) =>
    category.scripts.map((script) => ({
      name: `${category.name}_${script.name}`, // Changed from dot to underscore
      description: `[${category.description}] ${script.description}`,
      inputSchema: script.schema || {
        type: "object",
        properties: {},
      },
    })),
  ),
}));

src/framework.ts:235-281 (handler)

MCP CallToolRequestSchema execution handler for messages_get_messages. Parses tool name by splitting on '_', locates 'messages' category and 'get_messages' script, invokes script function with arguments to generate AppleScript, then executes via osascript.

this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const toolName = request.params.name;
  this.log("info", "Tool execution requested", { 
    tool: toolName,
    hasArguments: !!request.params.arguments
  });
  
  try {
    // Split on underscore instead of dot
    const [categoryName, ...scriptNameParts] =
      toolName.split("_");
    const scriptName = scriptNameParts.join("_"); // Rejoin in case script name has underscores

    const category = this.categories.find((c) => c.name === categoryName);
    if (!category) {
      this.log("warning", "Category not found", { categoryName });
      throw new McpError(
        ErrorCode.MethodNotFound,
        `Category not found: ${categoryName}`,
      );
    }

    const script = category.scripts.find((s) => s.name === scriptName);
    if (!script) {
      this.log("warning", "Script not found", { 
        categoryName, 
        scriptName 
      });
      throw new McpError(
        ErrorCode.MethodNotFound,
        `Script not found: ${scriptName}`,
      );
    }

    this.log("debug", "Generating script content", { 
      categoryName, 
      scriptName,
      isFunction: typeof script.script === "function"
    });
    
    const scriptContent =
      typeof script.script === "function"
        ? script.script(request.params.arguments)
        : script.script;

    const result = await this.executeScript(scriptContent);

src/index.ts:34-34 (registration)
Registers the 'messages' ScriptCategory (containing get_messages script) with the AppleScriptFramework server, making messages_get_messages available as an MCP tool.
```
server.addCategory(messagesCategory);
```

applescript-mcp