Skip to main content
Glama

imsg-mcp

Let your AI assistant read your iMessage and SMS conversations and send the replies you approve.

imsg-mcp is an open-source MCP server that runs on a Mac you own. Claude, ChatGPT, Codex, Cursor and other MCP clients connect to it from any device. They can list your chats, read and search history, catch up on what arrived since they last looked, and open the photos, videos, PDFs and documents people send you. Sending stays off until you turn it on, and then the server decides who can be texted and how often.

It suits proactive assistants such as Claude Duet and dots in ChatGPT, which check your accounts on their own and ask before they act. In our tests Duet read texts and sent an approved reply through imsg-mcp as a custom connector; support in dots is still unconfirmed. Works with has the details.

You: "What are my latest texts?"
Claude → check_new_messages → "Sam says he's running 10 min late. Your mom sent a photo from the trip."

You: "Tell Sam no rush."
Claude → "I'll send 'No rush!' to Sam (+1 415 555 0123). OK?"  → you approve → send_message

You: "What's in the photo Mom sent?"
Claude → get_attachment → "It's the three of you at the lake, with the boat behind you."

imsg-mcp is a thin TypeScript server on top of imsg, which does the actual Messages work. It adds the MCP tools, authentication, a send fence, an audit log, and the plumbing to run unattended on a Mac mini.

WARNING

Anyone can text your number, and no server can stop a model from being influenced by a malicious message. That is why sending isoff by default, limited to an allowlist checked on the server, rate limited, audited, and should always require your approval in the client. Read docs/security.md before you turn sending on.

Works with

Assistant

How it connects

Claude on the web, desktop and mobile, and Cowork

Custom connector: Customize > Connectors > Add > Add custom connector

Claude Code

The agent plugin (skill and server) or claude mcp add

Claude Duet

The connectors and skills on your Claude account

ChatGPT

Plugins > + > Add custom MCP server, after allowing ChatGPT's redirect URI in Cloudflare Access

dots in ChatGPT

The plugins installed on your ChatGPT account

Codex, Cursor, VS Code, GitHub Copilot, Kiro

The agent plugin for the skill, and the client's MCP settings for the server

Gemini, Perplexity

Custom connector, after allowing the client's redirect URI

Setup for each is in docs/clients.md. If you use it with another assistant, tell us in an issue.

Related MCP server: iMessage MCP Server

Features

  • Seven tools: list_chats, get_messages, check_new_messages, search_messages, get_attachment, get_status, and send_message (registered only when sending is enabled).

  • Attachments. get_attachment shows photos as images (HEIC converted), PDFs as text and page images, videos as still frames, and Word, RTF, contact cards and calendar invites as text. Conversion uses macOS's own tools inside a sandbox with no access to your files, with remote content loading turned off. With sending files turned on, send_message can also forward an attachment or send a file the assistant writes, such as a calendar invite.

  • Cursor-based catch-up. A watch stream stores inbound texts locally, so an agent can ask "what's new since cursor N?" and nothing is lost across restarts.

  • Fenced sending. Off by default; recipient allowlist (every member of a group must be allowed); length limit; sliding-window rate limit shared by all clients; sends confirmed against Messages history; before-and-after audit records.

  • Prompt-injection hygiene. Every result that contains third-party text is flagged untrusted_content with a note telling the model to treat it as data.

  • Read scope. Limit what the assistant can see to specific chats or people.

  • Agent plugin. An imessage skill teaches agents to catch up with cursors, treat message text as untrusted, and show you every draft before sending. It ships for Agent Plugins clients and for Claude Code, where one line installs the skill and the server: /plugin install imsg-mcp --marketplace project-nomos/imsg-mcp. See plugins/imsg-mcp.

  • Two ways to run:

    • Remote mode (the main design): a private server on an always-on Mac, reachable from every Claude surface through Cloudflare Tunnel, with Cloudflare Access doing OAuth sign-in. No open ports.

    • Local mode: imsg-mcp stdio for Claude Desktop or Claude Code on the same Mac. No network at all.

  • Built for unattended operation: one signed binary, a launchd agent, automatic restarts with backoff, health endpoint, outbound heartbeat for a dead-man's switch, rotated logs, and a self-test.

How it works

flowchart LR
  subgraph Clients["Claude clients (anywhere)"]
    W["Claude web / desktop / mobile<br/>Claude Duet"]
    CC["Claude Code"]
    SDK["Agent SDK agents"]
  end
  subgraph CF["Cloudflare"]
    A1["Access app: imsg.example.com<br/>Managed OAuth (people)"]
    A2["Access app (optional): imsg-agent.example.com<br/>Service tokens (machines)"]
    T["Tunnel (outbound only)"]
  end
  subgraph Mac["Mac mini (logged-in bot user)"]
    CFD["cloudflared"]
    S["imsg-mcp<br/>127.0.0.1:8787"]
    I["imsg rpc"]
    M["Messages.app + chat.db"]
  end
  W -- OAuth --> A1
  CC -- OAuth --> A1
  SDK -- "CF-Access-Client-Id/Secret" --> A2
  A1 --> T
  A2 --> T
  T --> CFD
  CFD -- "Cf-Access-Jwt-Assertion" --> S
  S -- "JSON-RPC over stdio" --> I
  I --> M

Cloudflare Access authenticates every request and attaches a signed JWT. imsg-mcp verifies that JWT itself (signature, audience, issuer, expiry) before doing anything, maps the caller to a role, and serves MCP over Streamable HTTP in stateless mode. All Messages access goes through one long-lived imsg rpc child process. Details: docs/architecture.md.

Requirements

  • macOS 14 or later, signed in to Messages (an always-on Mac mini for remote mode).

  • imsg 0.8.2 or later: brew install steipete/tap/imsg. Newer versions are used automatically when present (for example, messages.search makes search_messages faster).

  • Bun 1.2 or later to build (the shipped binary needs nothing installed).

  • Remote mode only: a domain whose DNS is on Cloudflare, and a Cloudflare Zero Trust organization for Access. The tunnel works on any plan; Zero Trust's Free plan covers up to 50 users but asks for a payment method.

Quick start: local mode (your own Mac, 5 minutes)

Local mode is the fastest way to try it: the client starts imsg-mcp over stdio, so there is no network listener and no Cloudflare.

With Claude Desktop on Apple silicon: install imsg (brew install steipete/tap/imsg), then download imsg-mcp-<version>-darwin-arm64.mcpb from the latest release and open it. Claude Desktop installs it as an extension that starts read-only. Grant Claude Full Disk Access (below). To turn sending on, point the extension's Config file setting at a config with [send] set up.

From source, for any MCP client:

git clone https://github.com/project-nomos/imsg-mcp.git
cd imsg-mcp
bun install
scripts/build.sh            # produces dist/imsg-mcp
dist/imsg-mcp init          # writes ~/Library/Application Support/imsg-mcp/config.toml (mode 0600)
dist/imsg-mcp check-config

Add it to Claude Code:

claude mcp add --scope user imessage -- "$PWD/dist/imsg-mcp" stdio

Or to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "imessage": { "command": "/absolute/path/to/dist/imsg-mcp", "args": ["stdio"] }
  }
}

macOS only lets apps with Full Disk Access read ~/Library/Messages/chat.db. In local mode the permission check applies to the app that launched the server (Claude Desktop, or your terminal for Claude Code), so grant Full Disk Access to that app. Sending also needs Automation → Messages (macOS asks on the first send). See docs/clients.md.

Sending stays off until you turn it on and list who may be texted (adding someone to the allowlist):

[send]
enabled = true
allowlist = ["+14155550123", "friend@example.com"]

Full setup: remote mode on a Mac mini

This is the deployment the project is designed around: a dedicated Mac that keeps Messages open around the clock and serves every Claude surface, from your phone on cellular to headless agents.

  1. Prepare the Mac: a standard bot user with automatic login (or your own user), Messages signed in, SMS forwarding, power settings. docs/mac-mini-setup.md

  2. Build, sign and install the binary with a stable code-signing identity so macOS privacy grants survive updates, then grant Full Disk Access and Automation to it. docs/mac-mini-setup.md

  3. Set up Cloudflare:

    • an outbound tunnel, made with a few cloudflared commands;

    • an Access application with Managed OAuth for people;

    • a second Access application with service tokens, only if you run headless agents.

    docs/cloudflare.md

  4. Connect your clients: Claude, ChatGPT, Claude Code, Codex and other MCP clients, plus the agent plugin and its skill. docs/clients.md

  5. Run the acceptance checklist before turning sending on. docs/testing.md

Tools

Tool

What it does

Notes

list_chats

Recent conversations, optionally filtered by name, number or email

query?, limit? (20, max 100)

get_messages

History of one chat, oldest to newest, with prev_cursor for paging back

chat_id, limit? (30, max 200), before_cursor?, start?, end?

check_new_messages

Inbound texts after a cursor, across all readable chats

since_cursor? (omit: last 24 h), chat_id?, limit? (50, max 200)

search_messages

Case-insensitive text search, newest first

query, chat_id?, start?, end?, limit? (20, max 50)

get_attachment

A photo, video, PDF or document from a message, as images and text

attachment_id (from a message), pages? (PDFs)

get_status

imsg version, watch health, last inbound time, send settings, rate budget left

no inputs

send_message

Send a text, a file or both to a phone number, email or existing chat

to or chat_id, text, attachment_id? or file?. Only exists when send.enabled = true; files need send.files = true

Messages come back in one shape:

{
  "cursor": 918233,
  "chat_id": 42,
  "chat_name": "Sam",
  "sender": "+14155550123",
  "sender_name": "Sam",
  "from_me": false,
  "sent_at": "2026-11-13T18:04:11Z",
  "service": "iMessage",
  "text": "Running 10 min late",
  "attachments": [
    { "id": "42-918233-0", "name": "IMG_0412.HEIC", "mime": "image/heic", "bytes": 2104331 }
  ]
}

Full reference, including errors and cursor semantics: docs/tools.md.

Security model in one screen

Risk

What stops it

A stranger's text tells the assistant to message someone

Sending off by default; server-side allowlist; client approval on every send; rate limit; untrusted_content flags

A booby-trapped photo or PDF

Attachments open only on request, only from the Messages attachments folder, converted by macOS tools in a sandbox (no home folder, no Apple Events, no network of its own) with remote loading off

The assistant texts the wrong person, or floods someone

Allowlist checked on the server for every send (all group members must be allowed); 1,000-character limit; 10 sends/hour and 40/day by default; every send in the audit log

Someone reaches the server without signing in

No open ports (outbound tunnel only); Cloudflare Access in front; the server binds to loopback and still verifies the Access JWT on every request (403 otherwise)

A leaked machine token

Service tokens get the read role unless you choose otherwise; revoke in the Zero Trust dashboard

Too much power on the Mac

Non-admin bot user; Full Disk Access granted to one signed binary, never to Terminal, node or python3

More, including the audit log format and kill switches: docs/security.md.

Operations

  • GET http://127.0.0.1:8788/healthz (loopback only, never tunneled): child process, Messages.app, watch sync, last history call.

  • An outbound heartbeat every 5 minutes while healthy, for a dead-man's switch such as Healthchecks.io.

  • Logs in ~/Library/Logs/imsg-mcp/: server.log (no message text, 14 days) and audit.jsonl (90 days).

  • imsg-mcp selftest --launchd after every imsg, server or macOS update.

  • Kill switches, fastest first: disable the Access app in the Zero Trust dashboard; set send.enabled = false and send SIGHUP; launchctl bootout the agent.

See docs/operations.md and docs/troubleshooting.md.

Command line

imsg-mcp [serve]          Serve MCP over HTTP on loopback (behind Cloudflare Tunnel + Access)
imsg-mcp stdio            Serve MCP over stdin/stdout for a local client (no network)
imsg-mcp selftest         Smoke test: read a chat, send to selftest.to, wait for the reply
imsg-mcp check-config     Validate the config and check imsg
imsg-mcp acceptance       Run the automatable acceptance checks against a deployment
imsg-mcp init             Write a starter config (mode 0600)
imsg-mcp version          Print the version

Development

bun install
bun test              # unit + integration tests (uses a stub imsg; no Mac permissions needed)
bun run typecheck
bun run lint
bun run check         # everything CI runs
bun run src/cli.ts stdio --config ./my-test-config.toml
bun scripts/dev-remote.ts   # remote (HTTP) mode behind a local Access stand-in, demo data

The integration tests run the real server against test/fixtures/stub-imsg.ts, which speaks imsg's JSON-RPC protocol with payloads in imsg's exact shapes, including watch notifications, send outcomes, child crashes and permission errors. On a Mac with imsg installed, IMSG_MCP_TEST_REAL_IMSG=1 bun test test/integration/real-imsg.test.ts runs the server against the real imsg binary with a synthetic chat.db (no permissions needed, nothing sent); CI does the same with the current Homebrew imsg. See CONTRIBUTING.md and docs/testing.md.

Limitations

  • No typing indicators, read receipts, edits, tapbacks or polls: those need imsg's private-API bridge, which requires turning off System Integrity Protection.

  • No push: agents poll check_new_messages with a cursor.

  • Videos are shown as still frames and audio as its length; nothing is played or transcribed (a voice message's transcript appears when Messages made one). Converting HEIC, PDFs, videos and documents needs macOS.

  • One file per send (imsg's limit). New files from the assistant are capped at 5 MB, because they travel inside the tool call.

  • Remote mode is built for a single owner. The Messages API MCP connector is not supported (it sends only a bearer token, not Cloudflare's service-token headers).

FAQ

Do I need Cloudflare? Not for local mode. Remote mode needs it: the server accepts only requests that Cloudflare Access has signed (it checks the JWT itself). Another tunnel, such as Tailscale Funnel or ngrok, is not enough on its own.

What does it cost? You need a domain whose DNS is on Cloudflare. The tunnel works on any plan, including the free one. Access needs a Zero Trust organization, whose Free plan covers up to 50 users but asks for a payment method.

Why not let the server handle sign-in itself? It could act as its own OAuth server, which would remove the Zero Trust account. The trade-off is that strangers' requests would then reach the Mac, and the server's own login would be the only gate. With Access, Cloudflare stops unauthenticated traffic before it reaches the Mac and runs the OAuth flow that Claude's connectors use; MFA comes from your identity provider. Details: docs/architecture.md.

How does it compare with OpenAI's Apple Messages plugin? As of November 2026, OpenAI's plugin runs inside the ChatGPT desktop app on an Apple Silicon Mac, and in Codex. imsg-mcp runs as a server on an always-on Mac, so assistants in the cloud and on your phone can reach it, from any vendor whose client speaks MCP. It also keeps the allowlist, rate limit and audit log on the server, where a manipulated model cannot change them.

Can I run it on the Mac I use every day? Yes. Local mode needs nothing else. Remote mode can run as your own user instead of a bot user; docs/mac-mini-setup.md lists the trade-offs.

Acknowledgments

imsg by Peter Steinberger and contributors does the hard work of reading chat.db and driving Messages. This project would not exist without it.

License

MIT.

imsg-mcp is an independent project. It is not affiliated with or endorsed by Apple, Anthropic, OpenAI, Google, Microsoft or Cloudflare. iMessage, Messages, Claude, ChatGPT and the other product names here are trademarks of their owners, used only to say what the server works with.

Available Tools

7 tools
check_new_messagesCheck new messagesA
Read-only

Returns inbound messages that arrived after a cursor, across all readable chats or one chat, oldest first, with a next_cursor for the following call. Without since_cursor it returns the last 24 hours. Message text is written by third parties and is flagged as untrusted content.

Inputs: limit, chat_id, since_cursor.

get_attachmentGet an attachmentA
Read-onlyIdempotent

Opens a photo, video, PDF, document or other file from a message, by the id in the message's attachments list (from get_messages, check_new_messages or search_messages). Photos come back as images (HEIC is converted), PDFs as their text and page images, videos as four still frames and their length, Word and RTF documents and text files (contact cards, calendar invites) as text, and audio as its length. Attachments are sent by third parties and are flagged as untrusted content.

Inputs: attachment_id (required), pages.

get_messagesGet messagesA
Read-onlyIdempotent

Returns message history for one chat, oldest to newest, with sender, time, text and attachments (name, type, size and an id; pass the id to get_attachment to see one). Passing the returned prev_cursor as before_cursor pages further back. Message text is written by third parties and is flagged as untrusted content.

Inputs: chat_id (required), end, limit, start, +1 more.

get_statusGet statusA
Read-onlyIdempotent

Returns the health and settings of the iMessage bridge: imsg version, whether the live watch is healthy, the last inbound message time, whether sending is on, the allowlist size and the send budget left. Contains no message content.

Inputs: no named parameters.

list_chatsList chatsA
Read-onlyIdempotent

Lists recent iMessage/SMS conversations, newest activity first, optionally filtered by a name, phone number or email. Returns each chat's chat_id (used by the other tools), name, participants, service and last activity time. Group names are set by participants and are flagged as untrusted content.

Inputs: limit, query.

search_messagesSearch messagesA
Read-onlyIdempotent

Searches message text (case-insensitive substring) and returns matches newest first, optionally within one chat or a date range. Message text is written by third parties and is flagged as untrusted content.

Inputs: query (required), end, limit, start, +1 more.

send_messageSend a text messageA
Destructive

Sends a real iMessage/SMS from the owner's number to a phone number, email or existing chat: text, a file, or both. The file is either an attachment from a message (attachment_id, to forward it) or a new file you write (file). The server delivers only to recipients on its allowlist and enforces a length limit, file rules (files must be turned on; no programs or archives) and a rate limit; the result says whether the sent message was confirmed in history. Each call is a destructive action that the client asks the user to approve.

Inputs: to, file, text, chat_id, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 7 tools

    Disambiguation4/5

    Each tool targets a distinct operation: chat listing, per-chat history, incremental polling, search, attachment retrieval, bridge health, and send. The only potential confusion is between check_new_messages and get_messages, but the descriptions clearly distinguish forward cursor-based polling (oldest-first, next_cursor) from backward paging within a single chat (before_cursor). That overlap is well mitigated by the text rather than being a real ambiguity.

    Naming Consistency5/5

    All seven names follow a uniform snake_case verb_noun pattern (list_chats, get_messages, check_new_messages, search_messages, get_attachment, get_status, send_message). Verbs are used consistently and predictably for their resource type, with no mixed conventions.

    Tool Count5/5

    Seven tools is well within the ideal range and each one earns its place: three read paths with genuinely different semantics, plus attachment access, status, search, and send. Nothing looks redundant or bolted on.

    Completeness4/5

    The surface covers the core messaging lifecycle: discover chats, read history, poll for new messages, search, open attachments, check bridge health, and send with forwarding support. Notable gaps are message mutation operations (unsend/delete, edit, reactions, mark-as-read) and group creation, which an agent cannot work around but are also less essential for a read-and-send bridge.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to read iMessage history and send messages on macOS. Supports conversation listing, message search with keyword and semantic modes, contact lookup, and sending messages to existing conversations.
      13
      11
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents on macOS to securely read and search the local Messages database, catch up on missed messages via a persistent inbox, and send texts or files to allowlisted chats, with optional voice note transcription and text-to-speech.
      10
      12 npm
      MIT