MCP Directory

How to add iMessage MCP to Claude Desktop

Read-only MCP server for searching and reading your macOS iMessage history and Contacts. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 28★ · stdio · no auth

Claude Desktop config for iMessage MCP

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

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the iMessage MCP config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm iMessage MCP's tools appear under the 🔌 tools menu.

Before you start

  • macOS (iMessage is only available on macOS)
  • Deno 2.x or later
  • Read access to ~/Library/Messages/chat.db
  • Read access to ~/Library/Application Support/AddressBook/ (for contacts search)

What iMessage MCP can do in Claude Desktop

search_messages

Search messages with optional filters: query text, handle (phone/email), startDate and endDate (ISO datetime), plus limit (1-200, default 100) and offset for pagination.

get_recent_messages

Get the most recent messages, with limit (1-100, default 20) and offset pagination.

get_chats

List all conversations/chats, with limit (1-200, default 50) and offset pagination.

get_handles

Get all contacts/handles, with limit (1-200, default 100) and offset pagination.

get_messages_from_chat

Get messages from a specific chat identified by chatGuid (required), with limit (1-200, default 50) and offset pagination.

search_contacts

Search the macOS AddressBook by firstName (required) and optional lastName, returning contact info with phone numbers and email addresses usable as handle parameters. Supports limit (1-200, default 50) and offset pagination.

Security

Runs with read-only access to the local iMessage database; no messages can be sent or modified, and only local data is accessed. Requires read access to ~/Library/Messages/chat.db and ~/Library/Application Support/AddressBook/ (typically needs Full Disk Access on macOS). Exposes private message history to the connected LLM, so use with care.

iMessage MCP + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the iMessage MCP config there under the "mcpServers" key and restart the client.

Is iMessage MCP safe to use with Claude Desktop?

Runs with read-only access to the local iMessage database; no messages can be sent or modified, and only local data is accessed. Requires read access to ~/Library/Messages/chat.db and ~/Library/Application Support/AddressBook/ (typically needs Full Disk Access on macOS). Exposes private message history to the connected LLM, so use with care.

Can it send or modify messages?

No. The server has read-only access to the local iMessage database; no messages can be sent or modified, and it only accesses local data.

What permissions does it need on macOS?

Read access to ~/Library/Messages/chat.db and ~/Library/Application Support/AddressBook/. On macOS this generally requires granting Full Disk Access to the process running Deno.

How do I run it without installing globally?

Run it directly from JSR: deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp

View repo Full iMessage MCP page