messages_search_messages
Search iMessage conversations for specific text, sender, or within a chat ID, with options to limit results by date and quantity.
Instructions
[iMessage operations] Search for messages containing specific text or from a specific sender
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chatId | No | Limit search to a specific chat ID | |
| daysBack | No | Limit search to messages from the last N days | |
| limit | No | Maximum number of messages to retrieve | |
| searchText | Yes | Text to search for in messages | |
| sender | No | Search for messages from a specific sender (phone number or email) |
Implementation Reference
- src/categories/messages.ts:120-149 (schema)Input schema defining parameters for the messages_search_messages tool (searchText required, optional filters for sender, chat, limit, recency).schema: { type: "object", properties: { searchText: { type: "string", description: "Text to search for in messages", default: "" }, sender: { type: "string", description: "Search for messages from a specific sender (phone number or email)", default: "" }, chatId: { type: "string", description: "Limit search to a specific chat ID", default: "" }, limit: { type: "number", description: "Maximum number of messages to retrieve", default: 50 }, daysBack: { type: "number", description: "Limit search to messages from the last N days", default: 30 } }, required: ["searchText"]
- src/categories/messages.ts:151-232 (handler)AppleScript handler for messages_search_messages: dynamically builds SQL WHERE clause from args, queries ~/Library/Messages/chat.db, returns formatted message 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_search.XXXXXX") -- Build WHERE clause based on provided parameters set whereClause to "" ${args.searchText ? ` -- Add search text condition if provided set whereClause to whereClause & "message.text LIKE '%${args.searchText.replace(/'/g, "''")}%' " ` : ''} ${args.sender ? ` -- Add sender condition if provided if length of whereClause > 0 then set whereClause to whereClause & "AND " end if set whereClause to whereClause & "handle.id LIKE '%${args.sender.replace(/'/g, "''")}%' " ` : ''} ${args.chatId ? ` -- Add chat ID condition if provided if length of whereClause > 0 then set whereClause to whereClause & "AND " end if set whereClause to whereClause & "chat.chat_identifier = '${args.chatId.replace(/'/g, "''")}' " ` : ''} ${args.daysBack ? ` -- Add date range condition if length of whereClause > 0 then set whereClause to whereClause & "AND " end if set whereClause to whereClause & "message.date > (strftime('%s', 'now', '-${args.daysBack} days') - strftime('%s', '2001-01-01')) * 1000000000 " ` : ''} -- If no search parameters were provided, add a default condition to avoid returning all messages if length of whereClause = 0 then set whereClause to "1=1 " end if -- 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, chat.chat_identifier as chat_id 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 WHERE " & whereClause & " 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:222-231 (registration)Registers the tool 'messages_search_messages' in the MCP listTools response by combining category 'messages' and script 'search_messages' names with underscore.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/index.ts:34-34 (registration)Registers the 'messages' category (containing search_messages script) with the framework, making its tools available.server.addCategory(messagesCategory);
- src/index.ts:11-11 (registration)Imports the messages category definition containing the search_messages script.import { messagesCategory } from "./categories/messages.js";