imsg-mcp
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, andsend_message(registered only when sending is enabled). - Attachments.
get_attachmentshows 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_contentwith 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
imessageskill 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 »).
https://github.com/project-nomos/imsg-mcp/releases/download/v0.2.0/imsg-mcp-0.2.0-darwin-arm64.mcpbDocumentation
Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.
Sommaire
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
| 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.
Features
- Seven tools:
list_chats,get_messages,check_new_messages,search_messages,get_attachment,get_status, andsend_message(registered only when sending is enabled). - Attachments.
get_attachmentshows 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_messagecan 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_contentwith 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
imessageskill 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 stdiofor 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).
imsg0.8.2 or later:brew install steipete/tap/imsg. Newer versions are used automatically when present (for example,messages.searchmakessearch_messagesfaster).- 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.
- 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
- 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
Set up Cloudflare:
- an outbound tunnel, made with a few
cloudflaredcommands; - an Access application with Managed OAuth for people;
- a second Access application with service tokens, only if you run headless agents.
- an outbound tunnel, made with a few
- Connect your clients: Claude, ChatGPT, Claude Code, Codex and other MCP clients, plus the agent plugin and its skill. docs/clients.md
- 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) andaudit.jsonl(90 days). imsg-mcp selftest --launchdafter every imsg, server or macOS update.- Kill switches, fastest first: disable the Access app in the Zero Trust dashboard; set
send.enabled = falseand sendSIGHUP;launchctl bootoutthe 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_messageswith 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.