iMessage

Provides local access to iMessage conversations by reading macOS databases and enabling read, search, and send actions via MCP clients.

typescript

9

GitHub Stars

typescript

Language

3 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "sameelarif-imessage-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/imessage-mcp/dist/index.js"
      ],
      "env": {
        "DEBUG": "false",
        "LOG_LEVEL": "info"
      }
    }
  }
}

You can read, search, and send iMessages directly from MCP-compatible clients on your Mac without exposing your data to the cloud. This local server reads your iMessage database files and serves a set of tools to manage conversations, messages, and attachments through a standard MCP interface.

How to use

Use your MCP client to connect to the iMessage MCP Server running on the same Mac where your iMessages are loaded. You can read recent messages with filters, view conversation histories, search across messages, and send new messages with text, images, or files. Attachments can be browsed and filtered by type, and you can manage read/unread status from the client interface.

How to install

Prerequisites and setup steps are as follows. Ensure you are on macOS with iMessage configured and you have Node.js 18 or later installed.

# 1) Clone the MCP server repository
git clone https://github.com/sameelarif/imessage-mcp.git
cd imessage-mcp

# 2) Install dependencies
pnpm install

# 3) Build the project
pnpm build

Configuration and runtime details

The server runs locally and reads your iMessage databases from your user directory. To enable easy access from your MCP client, configure the server as a stdio MCP endpoint.

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/absolute/path/to/imessage-mcp/dist/index.js"]
    }
  }
}

Environment variables

Control logging and debugging behavior using environment variables. The following are available in this server configuration.

{
  "LOG_LEVEL": "info",  
  "DEBUG": "false"
}

Available tools

get-messages

Get messages with filters (sender, date, service, attachments)

get-unread-messages

Get unread messages grouped by sender

search-messages

Search messages by text content

send-message

Send a text message

send-image

Send an image

send-file

Send a file attachment

get-conversation

Get full chat history with a contact

get-recent-conversations

Overview of recent chats

get-chat-messages

Get messages from a specific chat/group

get-attachments

Get messages with attachments

get-conversation-attachments

Get all attachments from a conversation

send-files

Send multiple files at once