mac-imessage-mcp
Reads and sends iMessages and SMS through macOS Messages, with tools for finding contacts, listing chats, reading and searching messages, and sending text or files under configurable approval modes.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| Search Contacts by name, nickname, company, phone digits or email. Shows each number/email and its existing conversation. |
| Recent conversations (1:1 and group) with participants, |
| Messages in a conversation, oldest first. Accepts a contact name, phone/email or |
| Case-insensitive search across all messages or one conversation. |
| Send text and/or files from your Apple ID, following your send mode. |
| Current send mode, smart-mode rules, and anything waiting for approval. |
| Switch between |
Related MCP server: lane-mac-mcp
Send modes
Mode | What happens when Claude sends |
| Every message waits for your approval. |
| Routine replies go out on their own; everything else waits for your approval. |
| 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 restartOr 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 | bashThe 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:
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 readchat.dbwithout this.Quit and reopen Claude Desktop.
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-arm64When 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 -- --httpThis 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; orif your account offers Request headers: URL
https://<your-host>/mcpand headerauthorization=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) removessend_messageentirely. 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
askorsmart, sends need your approval in your own self-chatevery send attempt, approval and mode change is recorded in
~/.mac-imessage-mcp/sends.log1 MB request limit;
chat.dbis opened read-only
In Claude you can also set send_message to require approval, or block it, per connector.
Configuration
Env var | Default | |
|
| Initial send mode ( |
| your own number | Where approval requests are texted |
|
| Country code for numbers typed without |
|
| Send cap per rolling hour; |
| — | Use this token instead of the token file (24+ chars) |
|
| HTTP bind address |
| — |
|
|
| Token and send log location |
mac-imessage-mcp --help lists the command-line flags.
How it works, and limitations
Reading: opens
~/Library/Messages/chat.dbread-only. On recent macOS most message text lives only inattributedBody, a typedstream blob, so search decodes those blobs instead of relying on SQLLIKE. The decoder handles typedstream's0x81(int16) and0x82(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 useapproval 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 binaryThe 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
Send and read WhatsApp, email and SMS from Claude, ChatGPT, Cursor or any MCP client, from your own accounts: your WhatsApp number (linked by QR code), your mailbox (IMAP/SMTP) and your Android phone (SMS from its SIM). Tools: list-accounts, get-account, add-account, add-email-account, list-messages, send-message (one channel or several in one call). Hosted, OAuth 2.1, nothing to install. Free plan with unlimited messages; paid plans from 19 EUR/month remove the footer and add media and webhooks. Docs and client configs: github.com/UnlimitedMessaging/unlimited-messaging-mcp
Send and read iMessages from your own Mac and Apple ID — drafts, history and contacts.
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.6MIT
- FlicenseNot gradedqualityDmaintenanceA 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.-
- AlicenseAqualityBmaintenanceEnables AI assistants to read Apple Messages chat history and send iMessages or SMS on macOS, accessible locally via stdio or remotely over authenticated HTTP.5MIT
- AlicenseAqualityCmaintenanceEnables 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.11336 npmMIT