iMessage

A Model Context Protocol server for reading iMessage data from macOS.

typescript

18

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months 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": {
    "wyattjoh-imessage-mcp": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ]
    }
  }
}

This MCP server provides a focused interface for accessing iMessage data on macOS and exposing it to language model workflows. It lets you search messages, retrieve chats and contacts, and fetch recent messages securely from your local iMessage database without altering anything on your system.

How to use

You interact with the iMessage MCP server through an MCP client. Use the available tools to search messages, list chats, fetch recent messages, or look up contacts. Each operation runs locally against your macOS iMessage data and returns structured results that you can feed into your automation or AI workflows. To get started, run the MCP server and point your client to the local instance. No data leaves your machine.

How to install

Prerequisites you need before installing: macOS with iMessage access, and Deno installed (version 2.x or later). Ensure you can read the iMessage database at ~/Library/Messages/chat.db and, for contacts, read access to ~/Library/Application Support/AddressBook/.

deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp

deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcp

Additional notes

You can also integrate with Claude Desktop by configuring the MCP server in claude_desktop_config.json. The server is designed to run locally and only reads data from your machine so there is no network exposure.

Available tools

search_messages

Search messages with optional filters: query text, handle (phone/email), startDate, endDate, limit, and offset. Returns matching messages with their metadata.

get_recent_messages

Retrieve the most recent messages with optional limit and offset to paginate results.

get_chats

List all conversations or chats with optional limit and offset for pagination.

get_handles

Fetch all contacts/handles available from the iMessage data with optional pagination.

get_messages_from_chat

Get messages from a specific chat identified by chatGuid, with optional limit and offset.

search_contacts

Search macOS Contacts by name and obtain associated phone numbers and emails that can be used as handles