<div align="center">

💬 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

</div>

---

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.

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)

<details> <summary>Option C — clone the repo</summary>

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

</details>

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:

Permission	Why	How
Full Disk Access	read your Messages database	The installer prints a Python path and opens the pane — add it with + (or ⌘⇧G to paste the path) and toggle it on
Automation → Messages	send texts	A dialog pops up the first time it sends — click Allow

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

Tool	What it does
list_chats	recent conversations + chat_id + resolved contact name
read_history	messages in a chat (group senders resolved to names)
search_messages	full-text search your history
find_contact	name → phone/email, so "text Mom" works
whois	is a handle reachable on iMessage
catch_up	"what did I miss" across recent chats in one call
send_message	send a text
send_attachment	send an image/file (+ optional text)
react	tapback the latest message
bridge_status	self-diagnose: health, contacts, send count, recipe link

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

Menu bar app

Item	Action
Turn On / Off	start/stop the bridge (iMSG ● on, iMSG ○ off)
Copy Recipe Link	your personal Poke link
Open Logs Folder	~/.imsg-bridge

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

Configuration

Set in the launchd plist or environment:

Variable	Default	Purpose
IMSG_SEND_LIMIT	30	max sends per hour
IMSG_SEND_ALLOWLIST	(unset)	comma-separated handles; if set, only those can be texted
IMSG_POKE_USER_ID	(set by installer)	your Poke account id — the server only accepts requests carrying it. Set automatically at install; don't change it
IMSG_MCP_TOKEN	(unset)	bearer token — set this only if you expose the server on a public URL; leave unset for the private Poke tunnel

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

Symptom	Fix
Menu bar icon missing	It runs as a LaunchAgent; check launchctl list | grep imsgbridge. Re-run ./install.sh if absent.
Poke says "offline / no available upstreams"	The tunnel isn't running. Click the menu bar item → Turn On, or check ~/.imsg-bridge/tunnel.log.
"can't read messages"	Full Disk Access isn't granted to the Python binary the installer printed.
Sends fail silently	Grant Automation → Messages (System Settings → Privacy & Security → Automation).
Poke can't reach it	Your Mac is asleep. Wake it.
Duplicate integrations in Poke	Delete extras at poke.com/settings; keep one.

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

---

<div align="center"> _{Built on <a href="https://github.com/steipete/imsg">imsg</a> · <a href="https://gofastmcp.com">FastMCP</a> · <a href="https://modelcontextprotocol.io">MCP</a>. Not affiliated with Apple or Poke.} </div>