Imessage MCP Server

AI-optimized MCP server for iMessage on macOS. Read, search, and send messages.

Local serverstdioPython

What is the Imessage MCP server?

Imessage MCP server exists for a simple reason — assistants are far more useful when they can act on Imessage directly instead of describing what you should do. AI-optimized MCP server for iMessage on macOS. Read, search, and send messages.

What you get

A high-performance MCP (Model Context Protocol) server for iMessage that lets AI agents read, search, and send your messages with proper contact resolution.

  • 12 Intent-Aligned Tools — - Work the way you naturally ask questions, not raw database queries
  • Contact Resolution — - See names instead of phone numbers via macOS Contacts
  • Smart Image Handling — - Efficient image variants (vision/thumb/full) to avoid token bloat
  • Session Grouping — - Messages grouped into conversation sessions with gap detection
  • Attachment Tracking — - Know which images are available locally vs offloaded to iCloud
  • Native Performance — - Swift with raw SQLite3, Core Image GPU acceleration

What the assistant can call

Once Imessage is connected, these are the calls the assistant has available:

  • find_chat — The find_chat tool exposed by this server
  • get_chat_details — Inspect a known thread without opening the full conversation
  • get_messages — Retrieve messages with flexible filtering. Returns metadata for media
  • get_attachment — Retrieve image content by attachment ID with resolution variants
  • list_chats — The list_chats tool exposed by this server
  • search — The search tool exposed by this server
  • get_context — The get_context tool exposed by this server
  • get_active_conversations — The get_active_conversations tool exposed by this server
  • list_attachments — Browse shared items grouped by message. Each row includes exact attachment ids for follow-up fetches
  • get_unread — Get unread threads or unread messages. Default is summary by chat
  • send — Send a message or file attachment (requires Automation permission for Messages.app)
  • diagnose — The diagnose tool exposed by this server

Configuration and credentials

  • macOS 13+ (Ventura or later) - Full Disk Access permission - Contacts permission (for name resolution) - Automation permission for Messages.app (send only)

Setting it up

Setup follows the usual MCP pattern — install or clone the server, register it in your client's configuration file, restart the client. The configuration blocks on this page cover the common clients.

Choosing this one

Plenty of database access servers cover similar ground. The differences that matter in practice are scope of access and how much setup stands between you and a working tool call. Imessage's toolset — find_chat, get_chat_details, get_messages and 9 more — is a fair guide to whether it matches your workflow. It is maintained by cyberpapiii; worth a glance at recent repository activity before you build anything load-bearing on it.

We check each listing at SyncDev against the project's documentation before it goes live — if something here drifts out of date, it is a bug worth reporting.

Before you rely on it

  • It runs with your machine's permissions. That is convenient and also the reason to think about what you point it at before you approve a tool call.
  • With 12 tools registered it takes up a noticeable share of the context window; turn it off in projects that never touch Imessage.
  • MCP clients confirm each tool call by default. Leave that on until you have watched what the imessage mcp server does with a few real requests.

Available tools

ToolWhat it does
find_chatThe find_chat tool exposed by this server.
get_chat_detailsInspect a known thread without opening the full conversation.
get_messagesRetrieve messages with flexible filtering. Returns metadata for media.
get_attachmentRetrieve image content by attachment ID with resolution variants.
list_chatsThe list_chats tool exposed by this server.
searchThe search tool exposed by this server.
get_contextThe get_context tool exposed by this server.
get_active_conversationsThe get_active_conversations tool exposed by this server.
list_attachmentsBrowse shared items grouped by message. Each row includes exact attachment ids for follow-up fetches.
get_unreadGet unread threads or unread messages. Default is summary by chat.
sendSend a message or file attachment (requires Automation permission for Messages.app).
diagnoseThe diagnose tool exposed by this server.

How to install the Imessage MCP server

**For source builds:**
```json
{
  "mcpServers": {
    "imessage": {
      "command": "/path/to/imessage-max/swift/.build/release/imessage-max"
    }
  }
}

Configuration as documented by the project. Restart the client after saving.

Configuration

  • macOS 13+ (Ventura or later) - Full Disk Access permission - Contacts permission (for name resolution) - Automation permission for Messages.app (send only)

Example prompts to try

  • Use Imessage to find chat.
  • Use Imessage to get chat details.
  • Use Imessage to get messages.

Frequently asked questions

It connects Imessage to MCP-compatible AI assistants such as Claude and Cursor, exposing 12 tools (find_chat, get_chat_details, get_messages, and more) that the assistant can call on your behalf. Instead of copying data back and forth by hand, the assistant works with Imessage directly.