wyattjoh/imessage-mcp

A Deno monorepo containing packages for iMessage access on macOS:
- **@wyattjoh/imessage** - Core library for read-only iMessage database access
- **@wyattjoh/imessage-mcp** - Model Context Protocol (MCP) server for LLM integration
Features
- Search messages by text content, contact, or date range
- Get recent messages
- List all chats/conversations
- Get all contacts/handles
- Retrieve messages from specific chats
- Search macOS Contacts by name with iMessage handle ID correlation
Requirements
- macOS (iMessage is only available on macOS)
- Deno 2.x or later
- Read access to ~/Library/Messages/chat.db, or to a custom database configured with IMESSAGE_DB_PATH
- Read access to ~/Library/Application Support/AddressBook/ (for contacts search)
Packages
@wyattjoh/imessage
Core library for accessing iMessage data:
See full documentation
@wyattjoh/imessage-mcp
MCP server for LLM integration:
For Claude Desktop app integration, add this to your claude_desktop_config.json:
Custom Messages Database
Set IMESSAGE_DB_PATH to open a read-only SQLite database at another location, such as a periodically refreshed snapshot of chat.db:
The process needs read access to the custom file. If Deno does not have permission to read IMESSAGE_DB_PATH, or the variable is empty or unset, the library uses ~/Library/Messages/chat.db without prompting for environment access.
Option 2: From Source
1. Clone this repository
2. Install dependencies:
3. Run the server:
Available Tools
1. **search_messages** - Search messages with filters
- query (optional): Text to search for
- handle (optional): Phone number or email to filter by
- startDate (optional): ISO datetime string for start date
- endDate (optional): ISO datetime string for end date
- limit (optional): Maximum results (1-200, default: 100)
- offset (optional): Pagination offset (default: 0)
2. **get_recent_messages** - Get the most recent messages
- limit (optional): Number of messages (1-100, default: 20)
- offset (optional): Pagination offset (default: 0)
3. **get_chats** - List all conversations
- limit (optional): Number of chats (1-200, default: 50)
- offset (optional): Pagination offset (default: 0)
4. **get_handles** - Get all contacts/handles
- limit (optional): Number of handles (1-200, default: 100)
- offset (optional): Pagination offset (default: 0)
5. **get_messages_from_chat** - Get messages from a specific chat
- chatGuid (required): The chat GUID
- limit (optional): Number of messages (1-200, default: 50)
- offset (optional): Pagination offset (default: 0)
6. **search_contacts** - Search macOS Contacts by name and get phone numbers
- firstName (required): First name to search for (e.g., 'John')
- lastName (optional): Last name to search for (e.g., 'Smith'). If omitted, searches across all name fields
- limit (optional): Maximum results (1-200, default: 50)