iMessage MCP Server & CLI

What is the iMessage MCP server & CLI?

The iMessage MCP server & CLI is a free, open source program that lets AI agents read, search and send your iMessages for you, in two ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to the Messages database right on your Mac.

The CLI is the same program as commands. imessage-cli inbox runs the same code your AI runs when you ask what you missed, whether an agent like Claude Code runs it or you do.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches iMessage. My guide to building an AI operating system names iMessage among the tools it reaches, and here's how I use AI myself.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
What did I miss?
What did Mike say about the invoice last month?
Text Anna that I'm running fifteen minutes late.
Transcribe that voice note.
Who have I not replied to this week?
Find the address someone sent me in March.

The first one shows why this is useful. The inbox keeps its place on disk, so it covers everything since you last asked, even while nothing was running.

It works well next to my Google Workspace MCP server and Telegram MCP server, so your AI can check your Gmail and catch up on your Telegram chats in the same chat. Every server I've made is on my MCP servers page.

For your messages, my free voice memo to text converter and text summarizer help too.

How to install the iMessage MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, and there's no account or key to add.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

Give it access to your messages

There's no sign-in. macOS asks twice, at different moments.

The first time it sends anything, macOS asks whether that app may control Messages. Allow it. That prompt appears once, and only if you send.

Check that it works

Run the doctor. It checks the database, your contacts, the inbox cursor and the voice note tools.

npx -y @thenavidm/imessage-mcp-cli doctor

If the database line fails, Full Disk Access is missing for the app that runs it, and remember the Cmd+Q.

In Claude Code, /mcp also shows whether the iMessage server is connected. It's one of the Claude Code commands worth knowing.

Use the iMessage CLI

The CLI is the same 10 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so search_messages runs as imessage-cli search-messages.

npm install -g @thenavidm/imessage-mcp-cli
imessage-cli
imessage-cli inbox --peek
imessage-cli search-messages --query "invoice" --limit 10
imessage-cli resolve-contact --name "Sarah"

The bare imessage-cli lists every command, imessage-cli which <words> finds the command for a task, and imessage-cli <command> --help shows what a command takes. Sending needs --confirm, the terminal's version of your approval.

imessage-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

A script can branch on the exit code:

MCP server or CLI: which one?

Both are the same program with the same 10 tools. The difference is when your AI pays for them, in the tokens it reads.

An app that loads every tool up front sends the full list with every message, whether you mention iMessage or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until iMessage comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 80 tokens.

When the whole conversation is about iMessage, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using it, with your AI app's own switch.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

The inbox remembers where you were

The inbox keeps its place in ~/.imessage-mcp/state.json, so you can close everything, come back two days later and ask what you missed. It's written safely, so a crash can't make it skip or repeat messages.

The first call returns nothing, because it starts at the end of your history rather than dumping years of messages. It includes your own sends, which makes note-to-self work, and includeFromMe: false leaves them out.

Voice notes

Transcription has 4 providers, and only one keeps the audio on your Mac.

Set IMESSAGE_TRANSCRIBE to choose, and put the provider's key in its environment variable. ffmpeg is needed for every provider.

Every iMessage tool

The tables below list all 10 tools, grouped the way the README groups them. Of these, seven only read, and the rest send, speak or move the inbox's place.

The inbox

Reading

Contacts

Sending

Voice

Status

Is the iMessage MCP server safe?

Reading changes nothing. Sending is the one thing to be careful with, because a message goes to a real person from your own account and can't be unsent, so every send asks first.

send_message, send_file and speak with a recipient ask first, marked "Asks first" in the tool tables above. The approval shows the recipient and the words, so you see exactly what would go before you say yes.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

• Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
• An app that can show forms asks you in a form.
• Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
• An agent with no person to ask needs IMESSAGE_CONFIRM=model, so its confirm: true counts in every app.
• In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches iMessage.

Make it read-only

Set IMESSAGE_READ_ONLY=1 and the three sending tools disappear from the list, so an agent that should only read never sees them. The inbox still works, because the only thing it writes is its own place on disk.

Keep a log of every write

Set IMESSAGE_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked, with what it was about to do and who approved it.

Your data

Nothing leaves your Mac, except in 2 cases. Voice transcription uploads the audio unless the provider is local, and speak sends its text to ElevenLabs.

The only thing this server writes is ~/.imessage-mcp/state.json, which holds one number and a timestamp. No message is copied, cached or indexed. Whatever your AI reads goes to its own model provider, like anything you paste into a chat.

iMessage MCP server settings

Every setting is optional, as an environment variable in your app's config.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.