imessage-mcp

A read-only MCP server for macOS that exposes your iMessage data over the Model Context Protocol (MCP), with automatic contact name resolution.

Use it with Cursor, OpenAI Codex, Claude Desktop, Claude Code, or any other MCP-capable client your terminal editor supports.

Setup

1. Install

cd ~/workspace/imessage-mcp
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Grant Full Disk Access

The server needs to read ~/Library/Messages/chat.db and the Contacts database. Grant Full Disk Access to the app that runs the server:

1. Open System Settings → Privacy & Security → Full Disk Access

2. For terminal-based MCP (Cursor agent, Claude Code, Codex in the terminal, etc.): add your terminal app (e.g., Terminal, iTerm2, Ghostty, Warp).

3. For Claude Desktop: add the Claude app itself.

3. Configure Cursor

In Cursor Settings → MCP (or your user MCP config, depending on Cursor version), register a server with the same command and args as in the Claude Code snippet below — only the host config file/path differs.

Example shape:

{
  "mcpServers": {
    "imessage": {
      "command": "<path-to-this-repo>/.venv/bin/python",
      "args": ["-m", "imessage_mcp"]
    }
  }
}

4. Configure Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "imessage": {
      "command": "/Users/jaredmoskowitz/workspace/imessage-mcp/.venv/bin/python",
      "args": ["-m", "imessage_mcp"]
    }
  }
}

5. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "imessage": {
      "command": "/Users/jaredmoskowitz/workspace/imessage-mcp/.venv/bin/python",
      "args": ["-m", "imessage_mcp"]
    }
  }
}

Tools

list_chats

List your iMessage chats sorted by recent activity.

• limit (optional, default 50): max chats to return

get_messages

Get messages from a specific chat.

• chat_id (required): chat identifier from list_chats

• limit (optional, default 50): max messages

• since (optional): ISO date string — only messages after this date

search_messages

Search all chats for messages containing a keyword.

• query (required): search text

• limit (optional, default 50): max results

Example Usage

"List my group chats" "Get the last 20 messages from my Business Ideas chat" "Search my messages for 'startup idea'"