iMessage MCP

I just published two packages that let you give Claude, GPT-4, or any MCP-compatible LLM read-only access to your iMessage database on macOS. Here's how to actually use them.

The @wyattjoh/imessage-mcp package is a Model Context Protocol server that exposes your iMessage database to LLMs. The @wyattjoh/imessage package is the core library if you want to build your own tools.

Both are now available on JSR:

• jsr.io/@wyattjoh/imessage
• jsr.io/@wyattjoh/imessage-mcp

Getting Started with Claude Desktop

Let me walk you through the setup. First, you'll need Claude Desktop (version 0.7.0 or later).

Edit your Claude Desktop configuration:

1# On macOS
2code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the iMessage server to your MCP servers:

1{
2  "mcpServers": {
3    "imessage": {
4      "command": "deno",
5      "args": [
6        "run",
7        "--allow-read",
8        "--allow-env",
9        "--allow-sys",
10        "--allow-ffi",
11        "jsr:@wyattjoh/imessage-mcp"
12      ]
13    }
14  }
15}

Restart Claude Desktop. You'll see a small plug icon showing the MCP connection is active.

Usage Examples

Once it's connected, you can ask Claude things like: "Show me all messages from John Smith in the last week"

Claude will:

1. Search your contacts for John Smith
2. Find his phone number
3. Search messages from that number
4. Paginate through all results (not just the first batch)

Here's what's happening behind the scenes:

1// Claude first searches contacts
2await searchContacts({
3  firstName: "John",
4  lastName: "Smith"
5});
6// Returns: ["+15551234567"]
7
8// Then searches messages with that handle
9await searchMessages({
10  handle: "+15551234567",
11  startDate: "2025-01-28T00:00:00Z"
12});

The Six Tools Available

The MCP server exposes six tools that cover most use cases:

1. Search Messages

1searchMessages({
2  query?: string,        // Full-text search
3  handle?: string,       // Phone or email
4  startDate?: string,    // ISO date
5  endDate?: string,      // ISO date
6  limit?: number,        // Max 200
7  offset?: number        // For pagination
8})

2. Get Recent Messages

1getRecentMessages({
2  limit?: number,   // Max 100
3  offset?: number   // For pagination
4})

3. Get Chats

1getChats({
2  limit?: number,   // Max 200
3  offset?: number   // For pagination
4})

4. Get Messages from Chat

1getMessagesFromChat({
2  chatGuid: string,  // From getChats()
3  limit?: number,
4  offset?: number
5})

5. Get All Handles

1getHandles({
2  limit?: number,
3  offset?: number
4})

6. Search Contacts

1searchContacts({
2  firstName: string,
3  lastName?: string,
4  limit?: number,
5  offset?: number
6})

Using the Core Library Directly

If you want to build your own tools instead of using the MCP server, install the core library:

1deno add @wyattjoh/imessage

Then use it directly:

1import {
2  openContactsDatabases,
3  openMessagesDatabase,
4  searchContactsByName,
5  searchMessages,
6} from "@wyattjoh/imessage";
7
8// Search for messages
9const db = openMessagesDatabase();
10const messages = await searchMessages(db, {
11  query: "meeting tomorrow",
12  limit: 50
13});
14db.close()
15
16// Search contacts
17const dbs = openContactsDatabases()
18const contacts = await searchContactsByName(dbs, "Alice");
19for (const db of dbs) {
20	db.close();
21}

Every function returns paginated results:

1interface PaginatedResult<T> {
2  data: T[];
3  pagination: {
4    limit: number;
5    offset: number;
6    total: number;
7  };
8}

Privacy and Security Notes

A few important things:

1. Read-only access - The packages can only read your messages, not send them
2. Local only - Everything runs on your machine, no data leaves your computer
3. macOS only - Requires access to ~/Library/Messages/chat.db and Contacts database files
4. Permission required - Deno will ask for file system access

Common Use Cases

Here are some things people are using this for:

Message Analysis

• "How many times did I mention 'project deadline' last month?"
• "What restaurants did Sarah recommend in our chats?"

Conversation Summaries

• "Summarize my conversation with Mom from last week"
• "What did the team discuss about the new feature?"

Contact Search

• "Find all messages from people named David"
• "Show me texts from unknown numbers"

Time-based Queries

• "What did I text about yesterday?"
• "Show me all weekend messages from December"

What's Next

The packages are open source and accepting contributions. Some ideas for the future:

• Export tools for backing up conversations
• Rich media support (images, attachments)
• Conversation analytics
• Windows/Linux support for other messaging databases

Try It Now

1. Install Claude Desktop
2. Add the configuration above
3. Ask Claude about your messages

Or grab the core library and build your own tools:

1deno add @wyattjoh/imessage

The full source is at github.com/wyattjoh/imessage-mcp.