jons-mcp-imessage

Return a friendly greeting.

This is an example tool that demonstrates the basic pattern for creating MCP tools with FastMCP. The docstring here becomes the tool's description in the MCP protocol.

Args: name: The name to greet. Defaults to "World".

Returns: A greeting message.

Check if the server has the required permissions to access iMessage data.

This tool helps debug permission issues by checking:

• Full Disk Access for ~/Library/Messages/chat.db

• Access to ~/Library/Messages/Attachments

Returns: Dictionary with access status, paths checked, and any error messages. Includes macOS version for debugging.

Search for contacts/handles in the iMessage database.

Searches by phone number or email address. Returns matching handles with their service type and conversation count.

Args: query: Search query (phone number or email, partial matches supported) limit: Maximum number of results to return (default: 20)

Returns: Dictionary containing: - results: List of matching handles with id, service, conversation_count - total: Total number of matches - query: The normalized search query

Look up a contact by phone number or email address.

Returns contact information if found in your Contacts, or None if not found. This tool explicitly resolves contacts from the macOS Contacts app.

Args: phone_or_email: The phone number or email address to look up.

Returns: Dictionary containing: - name: Contact's display name if found - matched_handle: The input phone/email that was matched - error: Error message if Contacts access is not available Or None if the contact is not found.

List all conversations with metadata.

Returns conversations sorted by most recent message, including:

• Participant information

• Contact names for participants

• Message count

• Last message preview

• Whether it's a group chat

Args: limit: Maximum number of conversations to return (default: 20) offset: Number of conversations to skip (default: 0)

Returns: Dictionary with conversations list and pagination metadata.

Get messages from a specific conversation.

You can specify the conversation by either chat_id or contact identifier. If contact is provided, it will be normalized and used to find the chat. Messages are enriched with contact names for senders.

Args: chat_id: Database row ID of the chat (from list_conversations) contact: Phone number or email to find the conversation limit: Maximum number of messages to return (default: 50) offset: Number of messages to skip (default: 0)

Returns: Dictionary with messages list, conversation info, and pagination.

Get the most recent messages across all conversations.

Args: limit: Maximum number of messages to return (default: 50) offset: Number of messages to skip (default: 0) after_date: Only return messages after this date (ISO8601 format)

Returns: Dictionary with messages list and pagination metadata.

Get messages surrounding a specific message in the same conversation.

Use this to get context around a message found via search. Returns messages from the same chat/thread, ordered chronologically, with the target message marked.

Args: rowid: The rowid of the message to get context for before: Number of messages to fetch before the target (default: 5) after: Number of messages to fetch after the target (default: 5)

Returns: Dictionary with: - messages: List of messages in chronological order - target_index: Index of the target message in the list - chat_id: The chat ID for the conversation - chat_identifier: The chat identifier (phone/email/group)

Search messages using hybrid keyword + semantic search.

Combines FTS5 full-text search with OpenAI embedding-based semantic search, merged using Reciprocal Rank Fusion (RRF) for optimal relevance.

This function is designed to handle partial failures gracefully:

• If sync fails, search uses existing index

• If semantic search fails, falls back to keyword search

• If keyword search fails, returns empty results rather than crashing

• Returns error information in response for visibility

Args: query: Search query text sender: Filter by sender phone/email (exact match after normalization) chat_id: Filter by specific conversation ID participants: Filter by chat participants (for group chats) after_date: Only messages after this date (ISO8601 format) before_date: Only messages before this date (ISO8601 format) service: Filter by "iMessage" or "SMS" search_mode: "hybrid" (default), "keyword" (FTS5 only), or "semantic" (vector only) limit: Results per page (default 100) offset: Pagination offset (default 0)

Returns: Dictionary with messages, pagination, and index_status including: - messages: List of matching messages with relevance scores - search_mode: The search mode that was used - fts5_matches: Number of keyword matches found - semantic_matches: Number of semantic matches found - pagination: Pagination metadata (total, limit, offset, has_more, next_offset) - index_status: Current state of the search index - errors: List of error messages encountered (if any) - warning: Warning message if partial results (optional)

Send a message to an existing conversation via AppleScript.

IMPORTANT LIMITATIONS:

• Can only send to contacts with EXISTING conversations in Messages

• No delivery confirmation - the message may silently fail to send

• Messages.app must be running

• Requires Automation permission for Messages.app

Args: recipient: Phone number or email address of the recipient message: The message text to send service: Service type - "iMessage" or "SMS" (default: iMessage)

Returns: Dictionary with success status and any warnings/errors.

Get the current status of the search index.

Returns information about the search index including:

• Total number of indexed messages

• Total number of messages with embeddings

• Last indexed message rowid

• Last embedded message rowid

• Schema version

• Database path and size

• Backfill status (if applicable)

Returns: Dictionary with search index status and metadata.

Rebuild the entire search index from scratch.

This will:

1. Clear the existing search index

2. Re-index all messages from chat.db

3. Update sync metadata

Note: This does NOT generate embeddings. Use a separate tool for that.

Args: background: If True, runs the rebuild in a background thread and returns immediately with progress tracking info. If False, blocks until complete.

Returns: Dictionary with rebuild status and progress information.

Get the current progress of a background index rebuild.

Returns: Dictionary with rebuild progress information, or status indicating no rebuild is in progress.