imessage-max — Claude Code MCP server for iMessage
A Swift MCP server that lets an agent read, search and send iMessage on macOS, turning phone numbers into contact names.
claude mcp add imessage-max -- uvx imessage-maxWhat imessage-max does
imessage-max ships as a single Swift binary with nothing to install at runtime. It reads chat.db read-only; sending requires Automation permission for Messages.app. The thirteen tools follow questions people actually ask rather than database tables: find_chat, get_messages, search, list_attachments, send and others.
Messages are grouped into sessions, split wherever the gap reaches 4 hours or more. Images come in three variants — vision at 1568px, thumb at 400px, and the original — so a photo need not arrive at full size. Attachment listings state whether a file sits on disk or has been offloaded to iCloud. Phone numbers map to names through macOS Contacts.
Full Disk Access has to be granted before the first run, otherwise ~/Library/Messages/chat.db stays unreadable. macOS applies that grant only to processes started afterwards, so relaunch the server once you change it. Contacts access is requested when the server starts from a terminal; a process launched headless by an MCP client never prompts, so run imessage-max --request-contacts-access from a terminal first and restart the service.
What it helps with
- find a conversation by person instead of by number
- pull the context around a message about a launch timeline
- see unread threads and active conversations from the last day
- fetch group chat photos at a smaller size
- send a message into the exact thread via
chat_id
Example prompts for the agent
- Find my chat with Alex and show what we discussed yesterday
- Search my messages for the launch timeline and show the surrounding context
- Send “use the latest draft” to
chat456
How to install imessage-max
Platform CLI
claude mcp add imessage-max -- uvx imessage-maxuvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>
Platform CLI
codex mcp add imessage-max -- uvx imessage-maxuvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>
Config file
{
"mcpServers": {
"imessage-max": {
"command": "uvx",
"args": [
"imessage-max"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>
Config file
{
"servers": {
"imessage-max": {
"type": "stdio",
"command": "uvx",
"args": [
"imessage-max"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>
Platform CLI
gemini mcp add imessage-max uvx imessage-maxuvx runs the command named after the package; if the README names another one, use uvx --from imessage-max <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about imessage-max
How do I install imessage-max in Claude Code?
Run claude mcp add imessage-max -- uvx imessage-max. Then grant Full Disk Access to the binary and restart the server.
What does imessage-max do?
It lets an agent read, search and send iMessage on macOS, resolving phone numbers to names from Contacts.
Why can't the server see my Contacts?
It only asks for access when started from a terminal, while an MCP client launches it headless. Grant access with imessage-max --request-contacts-access and restart the service.
