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 2 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.

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.

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.

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.

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, and imessage-cli <command> --help shows what a command takes. Sending asks for --confirm first, like it does for your AI.

These flags work on every command:

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 90 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 September 27, 2026 in Claude Code 2.1.257 with Claude Opus 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

All 10 tools, grouped the way the README groups them. 6 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 refuse to run without a confirm check, marked Asks first in the tool tables above. The refusal names the recipient and the text, so your AI can show you exactly what would go before it asks again.

Make it read-only

Set IMESSAGE_READ_ONLY=1 and the 3 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.

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.