iMessage Bridge

A Mac menu bar app that gives AI agents like Claude, Grok and Cursor access to your iMessages. You approve each agent and decide what it can do.

What it does

Ask your agent which messages need a reply, catch up on a group chat, find what someone said last month, or draft and send a text. The agent talks to the app, and the app reads your Messages history and sends through Messages.app. The agent never touches your Messages database directly.

• You approve every agent. A new agent shows up on your Mac with a 6-digit code. Nothing is shared until you click Approve.
• Each agent gets its own rules. Read only, or read and send. Limit it to a few conversations. Revoke it any time.
• You confirm every send. By default, each outgoing message pops up on your Mac for you to check first.
• Suspicious messages are filtered. Texts that try to give your agent instructions can be caught and hidden before it reads them.

Install

Requires macOS 14 or later. Takes about five minutes.

1. Install the app. Either way works:

   • Download: get the .dmg from the latest release, open it and drag iMessage Bridge to Applications.

   • Homebrew:

     brew install --cask cmer/tap/imessage-bridge
     

   Open the app. It lives in your menu bar (the two speech bubbles).

2. Grant Full Disk Access. On the Setup page, click Open Full Disk Access Settings and turn on iMessage Bridge. If you want agents to send messages, also click Request Permission next to "Control Messages".

3. Connect your agent. Click Copy next to the prompt on the Setup page and paste it into your agent (Claude Code, Grok Bot, or any agent that can run commands on your Mac). It sets itself up and asks whether it should be able to send messages or only read them. When the approval window appears, check that its code matches the one your agent shows you, then click Approve.

4. Turn on message screening (recommended). Anyone who texts you can write instructions your agent might follow. Screening checks incoming messages and hides suspicious ones from your agent. On the app's Safety page, click Download next to On this Mac (about 270 MB; the model runs on your Mac). For better coverage, also add an API key from TypeSafe under Jev. Screening is on whenever one of the two is. While you're there, add the people your agent may text without asking you first.

That's it. Ask your agent "Which of my messages need a reply?" to try it.

Advanced

Manual setup, client configuration and everything else. The same material is on the website's Advanced setup page (docs/advanced.html).

How it works

 Agent (Claude Code, Grok…)                      iMessage Bridge.app (menu bar)
 ─────────────────────────                       ──────────────────────────────
 stdio MCP ──► imessage-bridge mcp ──HTTP──►  127.0.0.1:7542/mcp ──► chat.db (read-only)
                (adds the agent's token)          │                    AddressBook (read-only)
                                                  │  per-agent         Messages.app via
 HTTP MCP client ─────────────Bearer token──────► │  permissions       AppleScript (send)
                                                  │
 Other computer ──── TLS, pinned certificate ──► :7543 (off by default)

The app runs an MCP server. It reads ~/Library/Messages/chat.db with SQLite and sends through AppleScript. Full Disk Access is granted to this app only, so agents only see what the app hands them.

To have an agent do the whole install, point it at AGENT_SETUP.md.

Pairing by hand

imessage-bridge pair --name "Claude Code" --read            # read only
imessage-bridge pair --name "Grok Bot" --read --send        # read and send

The command waits while an approval window on the Mac shows a 6-digit code. Check the code, adjust permissions if you like, and approve. The agent gets a random token; the app stores only its SHA-256 hash. When pairing finishes, the command prints setup snippets.

Connecting MCP clients

Each agent's page in the app has buttons to copy its setup, and imessage-bridge config --agent <name> prints it any time.

• Claude Code:

  claude mcp add imessage --scope user -- ~/.local/bin/imessage-bridge mcp --agent claude-code
  

• Claude Desktop, Cursor and other local MCP clients: add a stdio MCP server with command ~/.local/bin/imessage-bridge and args ["mcp", "--agent", "<name>"].

• Grok Bot: runs one command per tool call on your Mac. It doesn't need a connector: Grok Bot's custom connectors run in xAI's cloud, which can't reach your Mac, so delete any iMessage Bridge connector it added.

  imessage-bridge call --agent grok-bot                      # list tools and their arguments
  imessage-bridge call --agent grok-bot review_messages days=2
  imessage-bridge call --agent grok-bot send_message '{"to": "+15555550142", "text": "On my way"}'
  

  Arguments are typed by the tool, so phone numbers and message text stay text. In a new Grok Bot chat, click Copy Grok Bot Instructions on the agent's page and paste them.

Agent permissions

Each agent's page sets: read, send, ask before every send (a native dialog with the full message, Don't Send as the default; its "Don't ask again" checkbox turns this off), hide verification codes/card/SSN numbers, network access, and all conversations or only selected ones. With "only selected conversations", every tool, including contact lookup and sending, is limited to those chats. Sends are capped at 30 per hour per agent. The Activity page lists every tool call by agent; message text is never logged.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗