Skip to main content
Glama
mac-imessage-mcp

mac-imessage-mcp

by AshritVerma

mac-imessage-mcp

Let Claude, or any MCP client, read and send your iMessages and SMS.

It runs on your Mac, because that is the only Apple device where any app can reach Messages: iOS and iPadOS don't let apps read or send iMessages. Once it runs on a Mac, you can use it from that Mac (Claude Desktop) or from your iPhone, iPad, the web, or another computer through network mode.

 iPhone / iPad / web  ──HTTPS + token──▶  tunnel  ──▶  mac-imessage-mcp --http ─┐
                                                                                 ├─▶ chat.db (read-only)
 Claude Desktop on the Mac  ─────stdio─────────────▶  mac-imessage-mcp ──────────┤   Contacts
                                                                                 └─▶ Messages.app (send)

Tools

Tool

What it does

find_contact

Search Contacts by name, nickname, company, phone digits or email. Shows each number/email and its existing conversation.

list_chats

Recent conversations (1:1 and group) with participants, chat_id and a preview of the last message.

read_chat

Messages in a conversation, oldest first. Accepts a contact name, phone/email or chat_id; merges a person's threads across their numbers and emails. Date filters.

search_messages

Case-insensitive search across all messages or one conversation.

send_message

Send text and/or files from your Apple ID, following your send mode. to must be an exact phone, email or chat_id, never a bare name. dry_run reports what would happen without sending. Reports sent / delivered / failed from Messages' own records.

get_send_settings

Current send mode, smart-mode rules, and anything waiting for approval.

set_send_mode

Switch between ask, smart and auto. Tightening applies at once; loosening needs your approval.

Related MCP server: lane-mac-mcp

Send modes

Mode

What happens when Claude sends

ask (default)

Every message waits for your approval.

smart

Routine replies go out on their own; everything else waits for your approval.

auto

Every message sends immediately.

Approving from any device. When a message needs approval, the server texts you, in your own Messages self-chat:

Claude wants to send a message.
To: Alex Chen (+15551234567)
"Running 10 min late, start without me"
Why it's asking: smart mode: not a reply: they haven't messaged you in the last 24h

Reply "yes kmtp" to allow or "no kmtp" to cancel. Expires in 30 min.

Reply from your iPhone, iPad, Watch or Mac. Only a reply in your own self-chat with the exact code counts, so someone else texting you "yes kmtp" does nothing, and neither does the model. If you answer within 30 seconds, Claude gets the result in the same turn. If you answer later, the message still sends and you get a ✓ in the self-chat. Prefer a dialog on the Mac instead? mac-imessage-mcp approval dialog.

What counts as routine in smart mode: all of these must be true, otherwise it asks:

  • a 1:1 conversation (not a group) that you've sent at least 3 messages in

  • they messaged you within the last 24 hours, so this is a reply

  • 500 characters or fewer, and no attachments

Tune these in ~/.mac-imessage-mcp/config.json under "smart" (minSentByMe, replyWindowHours, maxChars, allowGroups, allowAttachments).

Changing the mode:

mac-imessage-mcp mode           # show settings and pending approvals
mac-imessage-mcp mode smart     # set (ask | smart | auto); takes effect immediately, no restart

Or ask Claude ("switch iMessage to ask mode"). Claude can make sending stricter on its own, but a looser mode only applies after you approve it the same way, so neither a model nor a message it reads can quietly turn on auto-send. Messages to yourself never need approval.

Since the server does the approving, you can set send_message to Always allow in Claude to avoid being asked twice.

Install

Requires macOS with Messages signed in. Tested on macOS 26 (Apple Silicon); Intel builds are included.

curl -fsSL https://raw.githubusercontent.com/AshritVerma/mac-imessage-mcp/main/install.sh | bash

The installer downloads the binary for your Mac, checks it against the release's SHA-256 checksums, puts it in ~/.mac-imessage-mcp/bin/, and adds it to Claude Desktop if Claude Desktop is installed (backing up the config first). It doesn't use sudo. Then:

  1. Grant Full Disk Access to the binary: System Settings → Privacy & Security → Full Disk Access → +, press ⌘⇧G, paste ~/.mac-imessage-mcp/bin/mac-imessage-mcp. macOS doesn't let any app read chat.db without this.

  2. Quit and reopen Claude Desktop.

  3. The first time it sends, macOS asks to let it control Messages. Click OK.

Uninstall: bash install.sh --uninstall.

Any stdio MCP client: point it at ~/.mac-imessage-mcp/bin/mac-imessage-mcp with no arguments.

From source (needs Bun):

git clone https://github.com/AshritVerma/mac-imessage-mcp && cd mac-imessage-mcp
bun install
bun src/server.ts            # stdio
bun run build                # standalone binaries in dist/
bash install.sh --from-file dist/mac-imessage-mcp-arm64

When run from source, Full Disk Access goes to the Bun binary (realpath $(which bun)) instead.

Network mode (iPhone, iPad, web, other machines)

curl -fsSL https://raw.githubusercontent.com/AshritVerma/mac-imessage-mcp/main/install.sh | bash -s -- --http

This adds a LaunchAgent that runs mac-imessage-mcp --http at login, serving MCP over Streamable HTTP at http://127.0.0.1:8765/mcp. Every request needs the access token, a random 256-bit value kept in ~/.mac-imessage-mcp/token (mode 600):

~/.mac-imessage-mcp/bin/mac-imessage-mcp --print-token    # show it
~/.mac-imessage-mcp/bin/mac-imessage-mcp --rotate-token   # replace it (old URLs/headers stop working)

Send it as Authorization: Bearer <token> (or X-API-Key: <token>), or put it in the URL as /mcp/<token> for clients that can't set headers.

The server listens only on this Mac by default. To reach it from elsewhere, put a tunnel in front of it. Don't open the port on your router.

Your own devices and MCP clients (private): with Tailscale, tailscale serve --bg 8765 gives you https://<mac-name>.<tailnet>.ts.net/mcp, reachable only from your tailnet.

Claude on iPhone, iPad and the web: Claude connects to custom connectors from Anthropic's cloud, not from your phone, so the server needs a public HTTPS address, for example tailscale funnel --bg 8765 or cloudflared tunnel --url http://127.0.0.1:8765. Then in Claude on the web, open Customize → Connectors → Add custom connector:

  • URL: https://<your-host>/mcp/<token>, authentication No sign-in; or

  • if your account offers Request headers: URL https://<your-host>/mcp and header authorization = Bearer <token>, which keeps the token out of URLs.

Connectors added on the web also show up in Claude's mobile apps. The Mac has to be awake and online.

Before you expose it

Anyone with the URL and token can read all your messages and, unless the server is read-only, send messages as you. Protections built in:

  • token required on every request, compared in constant time; failed attempts are slowed and logged

  • --read-only (bash install.sh --http --read-only) removes send_message entirely. Use it unless you need sending remotely.

  • at most 30 sends per hour by default (IMESSAGE_MAX_SENDS_PER_HOUR, 0 = no cap)

  • send modes: with ask or smart, sends need your approval in your own self-chat

  • every send attempt, approval and mode change is recorded in ~/.mac-imessage-mcp/sends.log

  • 1 MB request limit; chat.db is opened read-only

In Claude you can also set send_message to require approval, or block it, per connector.

Configuration

Env var

Default

IMESSAGE_SEND_MODE

ask

Initial send mode (mac-imessage-mcp mode overrides it)

IMESSAGE_APPROVAL_HANDLE

your own number

Where approval requests are texted

IMESSAGE_DEFAULT_COUNTRY_CODE

1

Country code for numbers typed without +

IMESSAGE_MAX_SENDS_PER_HOUR

30

Send cap per rolling hour; 0 disables

IMESSAGE_MCP_TOKEN

—

Use this token instead of the token file (24+ chars)

IMESSAGE_MCP_HOST / IMESSAGE_MCP_PORT

127.0.0.1 / 8765

HTTP bind address

IMESSAGE_MCP_READ_ONLY

—

1 = no send_message

IMESSAGE_MCP_HOME

~/.mac-imessage-mcp

Token and send log location

mac-imessage-mcp --help lists the command-line flags.

How it works, and limitations

  • Reading: opens ~/Library/Messages/chat.db read-only. On recent macOS most message text lives only in attributedBody, a typedstream blob, so search decodes those blobs instead of relying on SQL LIKE. The decoder handles typedstream's 0x81 (int16) and 0x82 (int32) length prefixes, so messages of 128+ bytes decode correctly.

  • Names come from the Mac's Contacts databases. If your iPhone shows names that the Mac doesn't, turn on Contacts sync for that account on the Mac.

  • If you also run an iMessage channel that forwards your self-chat to Claude, approval prompts and replies will show up there too. Point approvals elsewhere with IMESSAGE_APPROVAL_HANDLE, or use approval dialog.

  • Sending goes through Messages.app with AppleScript. Messages is sandboxed and rejects files from places like /tmp (error 25), so attachments are first copied to ~/Pictures/.mac-imessage-mcp-outbox/ and cleaned up after a day.

  • SMS/green bubbles work if your iPhone forwards texts to the Mac (Settings → Messages → Text Message Forwarding).

  • Reactions and system events (renames, members joining) are left out of results.

  • Message text is passed to the model as data with a note that it was written by other people. Be wary of anything that asks Claude to act on message contents.

Tests

bun run typecheck
bun test/decode.ts          # decoder vs. rows that store both text and attributedBody
bun test/e2e.ts             # stdio: drives every tool through a real MCP client (read-only)
bun test/http.ts            # HTTP: auth, routing, limits, read-only mode, tokens
bun test/policy.ts          # send modes: smart rules, dry runs on real chats, CLI toggle
SEND=1 bun test/e2e.ts      # + real sends (text and file) to your own self-chat
SEND=1 bun test/http.ts     # + send cap and audit log
SEND=1 bun test/policy.ts   # + live approve / decline / late-approve / mode-change flows in your self-chat
MCP_SERVER_BIN=dist/mac-imessage-mcp-arm64 bun test/e2e.ts   # test a compiled binary

The tests print full message text only from your self-chat.

License

Apache-2.0. parseAttributedBody is adapted from Anthropic's claude-channel-imessage plugin (Apache-2.0) and fixes its handling of long messages. Not affiliated with Apple or Anthropic.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A local MCP server that enables reading iMessage conversations and sending new messages through Claude Desktop. It provides secure, read-only access to your Mac's iMessage database and AppleScript-based message sending capabilities.
      6
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A read-only iMessage MCP server for macOS that lets you list conversations, read chats, and search message history through Claude or a CLI. It is auditable, dependency-light, and deliberately has no send capability.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible clients such as Claude, Cursor, Cline, and Codex to send and read iMessages from the user's own Mac and Apple ID, with tools for conversation history, contacts, drafts, and Mac connector health.
      11
      336 npm
      MIT