MCP Directory

How to add iMessage MCP to Cursor

Read-only MCP server for searching and reading your macOS iMessage history and Contacts. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the iMessage MCP config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of iMessage MCP's tools to confirm it's connected.

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 Cursor

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the iMessage MCP config there under the "mcpServers" key and restart the client.

Is iMessage MCP safe to use with Cursor?

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