💬 iMessage Bridge for Poke

Text Poke to read and send your iMessages.

A tiny server runs on your Mac, Poke reaches it over a private tunnel, and a menu bar switch turns it on and off. Your messages stay on your Mac — only what you ask Poke to read or send ever leaves it.

⬇️ Download · ⚡ Quick start · 🛠 How it works · ❓ FAQ

What it feels like

You: what did the last person text me? Poke: Sarah said "running 10 late, order me a flat white" — want me to reply? You: yeah tell her got it 👍 Poke: Sent ✅

You're texting an assistant that can actually reach into your real iMessages — from your phone, from anywhere, as long as your Mac is awake.

Related MCP server: jons-mcp-imessage

How it works

 your phone           Poke cloud            your Mac (awake)
┌──────────┐         ┌──────────┐    private tunnel   ┌────────────────────────────┐
│  text    │ ──────▶ │   Poke   │ ─────────────────▶ │ FastMCP server :8765        │
│  "Poke…" │         │  (LLM)   │ ◀───────────────── │   └▶ imsg CLI ▶ Messages.app │
└──────────┘         └──────────┘                     └────────────────────────────┘

Poke is an MCP host: it discovers the tools your server exposes and calls them mid-conversation. The server wraps imsg, a CLI that reads your local chat.db and drives Messages.app.

Each person runs their own copy. Recipe links are not shareable — a shared link would point Poke at your Mac and your texts. Share the repo, not your link.

Quick start

Prerequisites: macOS 12+, Homebrew, and a Poke account.

Option A — download the app (easiest)

1. ⬇️ Download the latest release and unzip it.

2. Right-click Install iMessage Bridge.app → Open → Open. (Needed once — the app is unsigned, so macOS asks you to confirm.)

3. A Terminal window runs the setup and walks you through the rest.

Option B — one command

bash <(curl -fsSL https://raw.githubusercontent.com/ish-cs/imessage-poke-bridge/main/install.sh)

git clone https://github.com/ish-cs/imessage-poke-bridge.git
cd imessage-poke-bridge
./install.sh

However you install, it sets everything up for your account: deps (imsg, Node, poke CLI, uv), the server + tunnel as background services, logs you into your Poke, mints your recipe link, and adds the menu bar app. Every install is fully self-contained — your Poke talks to your Mac, nobody else's.

Two permissions you must grant

macOS requires these and no installer can do them for you:

Then click iMSG ● in your menu bar (○ = off) and start texting Poke.

Using it

Text Poke naturally:

• "what did mom text me?"

• "tell Sarah I'm running 10 min late"

• "what did I miss today?"

• "send the photo at ~/Desktop/ticket.png to the group"

Works whenever your Mac is awake. Lid closed / asleep = the bridge is dark until you wake it. (We deliberately don't keep your Mac awake — your battery thanks us.)

Tools

Contact names come from your local AddressBook — covered by the Full Disk Access grant, so no extra Contacts permission.

Menu bar app

Auto-starts at login and self-restarts if it crashes.

Configuration

Set in the launchd plist or environment:

Safety & privacy

• Locked to your Poke account. Poke sends an X-Poke-User-Id on every request; the server only accepts your id (captured at install from your Poke login). Even if your recipe link leaked, someone else's Poke — a different user id — is rejected outright. The installer refuses to set up an unlocked bridge. The server also binds to 127.0.0.1, so it's only reachable through your own private Poke tunnel, never the open internet.

• Audit log — every send is appended to ~/.imsg-bridge/sends.jsonl. Review exactly what Poke did in your name.

• Rate limit + allowlist — guard rails on the send tools (see Configuration).

• Local-first — messages stay on your Mac; only what Poke acts on is sent to it.

⚠️ Anything in your messages — secrets, 2FA codes, private notes — becomes readable by Poke (an LLM). Don't text yourself API keys, and rotate any that are already in your history.

Troubleshooting

Logs live in ~/.imsg-bridge/ (server.log, tunnel.log, menubar.log).

Uninstall

./uninstall.sh

Removes the services, menu bar app, and files. Revoke Full Disk Access manually in System Settings, and remove the integration at poke.com/settings if you want.

Limitations

• Your Mac must be awake. iMessage only exists on your Mac; there's no free cloud option (a cloud Mac costs $100+/mo).

• SIP-on features only. Typing indicators, read receipts, edit/unsend, polls, and rich effects need SIP disabled and are intentionally not exposed.

• Not notarized yet. MVP installs from source.

• Contact matching is by last-10-digits, so some international numbers may mismatch.

FAQ

Does Poke get all my messages? No. The bridge only reads or sends when Poke calls a tool — i.e. when you ask it to. It doesn't stream your history anywhere. (That said, content Poke does read is processed by an LLM — see Safety & privacy.)

Can someone else use my link to read my texts? No. The server is locked to your Poke account via the X-Poke-User-Id Poke attaches to every request — another person's Poke is rejected even if they somehow got your link. On top of that, the server only listens on localhost and is reachable only through your own private tunnel. The thing you share is the app/installer: each person who installs it gets their own server, tunnel, and link wired to their Mac and their Poke. Installs are fully isolated.

Why does my Mac have to be awake? iMessage only lives on your Mac. There's no cloud copy to talk to, so when the Mac sleeps, Poke can't reach it. We don't force it awake — that's your battery's call.

Is it safe to run an unsigned app? The source is all here and the installer is a readable shell script — inspect both. The "unidentified developer" warning is just because it isn't notarized yet (roadmap); right-click → Open acknowledges that once.

Does this need SIP disabled? No. It uses only the features that work with System Integrity Protection on.

How do I turn it off? Click the menu bar item → Turn Off, or run ./uninstall.sh to remove it entirely.

Roadmap

• Signed + notarized .dmg installer — clean double-click, no warning

• Dependency-free Swift/Go rewrite — no Homebrew/Python/Node needed

Architecture

server.py     FastMCP server wrapping imsg — 10 tools, stateless HTTP,
              path-prefix shim for Poke's /<id>/mcp routing, optional bearer auth,
              AddressBook contact resolution, send audit + rate limit.
menubar.py    pyobjc menu bar controller for the launchd services.
install.sh    per-user setup: deps, services, recipe capture, menu bar agent.
uninstall.sh  teardown.

License

MIT © Ishaan Pandey