mac-imessage-mcp
by AshritVerma
README.md
# mac-imessage-mcp
Let Claude, or any [MCP](https://modelcontextprotocol.io) 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**.
```text
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](#send-modes). `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. |
## 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:
```text
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:**
```sh
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.
```sh
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`.
<details>
<summary>Other MCP clients, or running from source</summary>
Any stdio MCP client: point it at `~/.mac-imessage-mcp/bin/mac-imessage-mcp` with no arguments.
From source (needs [Bun](https://bun.sh)):
```sh
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.
</details>
## Network mode (iPhone, iPad, web, other machines)
```sh
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):
```sh
~/.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](https://tailscale.com), `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](#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
```sh
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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data