messages_get_messages
Retrieve messages from the macOS Messages app using specified limits, enabling integration with LLM applications via AppleScript operations.
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:74-116 (handler)Core handler logic for the 'get_messages' tool within the messages category. Generates AppleScript that queries ~/Library/Messages/chat.db for the most recent messages (limit default 100), formats dates, and returns tab-separated results.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/categories/messages.ts:64-73 (schema)Input schema defining the optional 'limit' parameter (number, default 100) for the messages_get_messages tool.schema: { type: "object", properties: { limit: { type: "number", description: "Maximum number of messages to retrieve", default: 100 } } },
- src/framework.ts:221-232 (registration)Tool registration in listTools handler: constructs tool name as 'messages_get_messages' from category 'messages' and script 'get_messages', provides description and inputSchema.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-294 (handler)Generic MCP tool call handler: parses 'messages_get_messages' into category 'messages' and script 'get_messages', invokes script function with arguments to generate AppleScript, executes via osascript, returns result as text content.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); this.log("info", "Tool execution completed successfully", { tool: toolName, resultLength: result.length }); return { content: [ { type: "text", text: result, }, ], };
- src/index.ts:33-35 (registration)Registers the messagesCategory (containing get_messages script) with the MCP server framework, making 'messages_get_messages' tool available.server.addCategory(shortcutsCategory); server.addCategory(messagesCategory); server.addCategory(notesCategory);