MCP Directory

How to add iMessage MCP to Windsurf

Read-only MCP server for searching and reading your macOS iMessage history and Contacts. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the iMessage MCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5iMessage MCP's tools become available to Cascade.

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 Windsurf

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

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the iMessage MCP config there under the "mcpServers" key and restart the client.

Is iMessage MCP safe to use with Windsurf?

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