Read Your iMessages with an MCP Server

4 min read Original article ↗

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:

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:

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

Add the iMessage server to your MCP servers:

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ]
    }
  }
}

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:

// Claude first searches contacts
await searchContacts({
  firstName: "John",
  lastName: "Smith"
});
// Returns: ["+15551234567"]

// Then searches messages with that handle
await searchMessages({
  handle: "+15551234567",
  startDate: "2025-01-28T00:00:00Z"
});

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

1. Search Messages

searchMessages({
  query?: string,        // Full-text search
  handle?: string,       // Phone or email
  startDate?: string,    // ISO date
  endDate?: string,      // ISO date
  limit?: number,        // Max 200
  offset?: number        // For pagination
})

2. Get Recent Messages

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

3. Get Chats

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

4. Get Messages from Chat

getMessagesFromChat({
  chatGuid: string,  // From getChats()
  limit?: number,
  offset?: number
})

5. Get All Handles

getHandles({
  limit?: number,
  offset?: number
})

6. Search Contacts

searchContacts({
  firstName: string,
  lastName?: string,
  limit?: number,
  offset?: number
})

Using the Core Library Directly

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

deno add @wyattjoh/imessage

Then use it directly:

import {
  openContactsDatabases,
  openMessagesDatabase,
  searchContactsByName,
  searchMessages,
} from "@wyattjoh/imessage";

// Search for messages
const db = openMessagesDatabase();
const messages = await searchMessages(db, {
  query: "meeting tomorrow",
  limit: 50
});
db.close()

// Search contacts
const dbs = openContactsDatabases()
const contacts = await searchContactsByName(dbs, "Alice");
for (const db of dbs) {
  db.close();
}

Every function returns paginated results:

interface PaginatedResult<T> {
  data: T[];
  pagination: {
    limit: number;
    offset: number;
    total: number;
  };
}

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:

deno add @wyattjoh/imessage

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