imsg-mcp

Registre officiel Recherche et web

iMessage and SMS for AI assistants, from a Mac you control. Read, search, send with approval.

Que pouvez-vous faire avec imsg-mcp ?

  • 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 ...
  • 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 ins...
  • Two ways to run:

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

MCPB package https://github.com/project-nomos/imsg-mcp/releases/download/v0.2.0/imsg-mcp-0.2.0-darwin-arm64.mcpb

Documentation

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  1. imsg-mcp
  2. Works with
  3. Features
  4. How it works
  5. Requirements
  6. Quick start: local mode (your own Mac, 5 minutes)
  7. Full setup: remote mode on a Mac mini
  8. Tools
  9. Security model in one screen
  10. Operations
  11. Command line
  12. Development
  13. Limitations
  14. FAQ
  15. Acknowledgments
  16. License

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 is off 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

AssistantHow it connects
Claude on the web, desktop and mobile, and CoworkCustom connector: Customize > Connectors > Add > Add custom connector
Claude CodeThe agent plugin (skill and server) or claude mcp add
Claude DuetThe connectors and skills on your Claude account
ChatGPTPlugins > + > Add custom MCP server, after allowing ChatGPT's redirect URI in Cloudflare Access
dots in ChatGPTThe plugins installed on your ChatGPT account
Codex, Cursor, VS Code, GitHub Copilot, KiroThe agent plugin for the skill, and the client's MCP settings for the server
Gemini, PerplexityCustom 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.

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

ToolWhat it doesNotes
list_chatsRecent conversations, optionally filtered by name, number or emailquery?, limit? (20, max 100)
get_messagesHistory of one chat, oldest to newest, with prev_cursor for paging backchat_id, limit? (30, max 200), before_cursor?, start?, end?
check_new_messagesInbound texts after a cursor, across all readable chatssince_cursor? (omit: last 24 h), chat_id?, limit? (50, max 200)
search_messagesCase-insensitive text search, newest firstquery, chat_id?, start?, end?, limit? (20, max 50)
get_attachmentA photo, video, PDF or document from a message, as images and textattachment_id (from a message), pages? (PDFs)
get_statusimsg version, watch health, last inbound time, send settings, rate budget leftno inputs
send_messageSend a text, a file or both to a phone number, email or existing chatto 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

RiskWhat stops it
A stranger's text tells the assistant to message someoneSending off by default; server-side allowlist; client approval on every send; rate limit; untrusted_content flags
A booby-trapped photo or PDFAttachments 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 someoneAllowlist 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 inNo 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 tokenService tokens get the read role unless you choose otherwise; revoke in the Zero Trust dashboard
Too much power on the MacNon-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.

Questions fréquentes

Qu'est-ce que imsg-mcp ?

iMessage and SMS for AI assistants, from a Mac you control. Read, search, send with approval.

Comment installer imsg-mcp ?

Suivez les étapes d'installation de sa documentation, affichée sur cette page et dans son dépôt.

Faut-il une clé API pour imsg-mcp ?

Son entrée au registre n'indique aucune clé ni secret obligatoire. Certaines fonctions peuvent tout de même demander un compte auprès du service auquel il se connecte.

imsg-mcp est-il open source ?

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient imsg-mcp ?

Il est publié par project-nomos. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.