imessage

imessage-mcp exposes a read-only set of 26 tools that let you query and analyze your local iMessage history without sending any data to the network. It reads from your Mac's local iMessage database (chat.db) and the AddressBook for contact resolution, and all processing happens locally on your machine. Use the MCP client you prefer (Claude, Cursor, VS Code, Codex CLI, etc.) to connect to the server named imessage and issue tool requests such as search_messages, yearly_wrapped, get_conversation, list_contacts, or get_reactions to build summaries, insights, or conversational AI prompts based on your message history. Every tool is annotated with readOnlyHint: true, so your client can present appropriate prompts and approvals for the read-only operations. The server does not modify, upload, or send your data anywhere; the AI assistant only receives information you explicitly request via the tools.

Typical usage flows involve starting the MCP server locally (often via npx imessage-mcp) and then adding the server configuration to your MCP client. For example, you can add the server under the imessage key with command npx and arguments [-y, imessage-mcp], then query tools like search_messages for a given query or date range, or use yearly_wrapped to get a year-in-review style summary of your messages.

Prerequisites

• macOS (iMessage is macOS-only)
• Node.js 18+ installed on your system
• Access to the local iMessage database (macOS permissions granted to the running CLI or app)

Installation steps

1. Install the MCP server package globally via npm:

npm install -g imessage-mcp

2. Verify installation by running the built-in doctor command (or the equivalent MCP client init you use):

npx imessage-mcp doctor

3. Add the MCP server to your MCP client configuration. For Claude or other clients, you can reference the following example:

// Claude Code / JSON config
{
  "mcpServers": {
    "imessage": {
      "command": "npx",
      "args": ["-y", "imessage-mcp"]
    }
  }
}

4. Start using the server through your MCP client by selecting the imessage server and issuing tool requests such as search_messages or yearly_wrapped.

Notes and tips:

• The server operates in read-only mode. No messages are modified, uploaded, or sent over the network.
• Ensure your macOS privacy permissions allow access to the iMessage database and AddressBook if needed by your workflow (System Settings > Privacy & Security).
• If you encounter permission prompts during first use, grant Full Disk Access to the terminal or application running the MCP server.
• The toolset includes 26 tools; consult your MCP client’s guide for usage patterns and example queries to maximize your ability to summarize and analyze conversations.
• If you’re using Claude Desktop or Claude Code, you can add the MCP server using the provided configuration snippet and reload the app to discover the new server.