home / mcp / mac messages mcp server

Mac Messages MCP Server

Provides a Python bridge to interact with macOS Messages via MCP, enabling sending, reading, and filtering messages across iMessage and SMS/RCS.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "carterlasalle-mac_messages_mcp": {
      "command": "uvx",
      "args": [
        "mac-messages-mcp"
      ]
    }
  }
}

Mac Messages MCP is a Python bridge that uses MCP to interact with the macOS Messages app. It lets you read recent messages, send messages with automatic delivery decisions, and filter or search messages across iMessage and SMS/RCS, providing a seamless experience on macOS.

How to use

You access Mac Messages MCP through an MCP client and a local runtime. Use the Python module to read messages and send new ones. Before sending, you can check whether a recipient supports iMessage to pick the best delivery method (iMessage or SMS). When composing messages, the MCP server automatically chooses iMessage for Apple devices and falls back to SMS/RCS for Android users.

Practical usage patterns include reading recent conversations, checking availability for an iMessage before sending, and sending messages to multiple recipients where each recipient is delivered via the most appropriate channel.

Example usage scenarios include sending a message to an iPhone user and another to an Android user in the same session, or querying availability before issuing a group message to ensure optimal delivery per recipient.

How to install

Prerequisites: macOS (tested on macOS 11+), Python 3.10+, and the uv runtime package manager.

Install the uv runtime on macOS with Homebrew.

brew install uv

Install the Mac Messages MCP package using Python's package manager.

uv pip install mac-messages-mcp

Alternatively, install from source by cloning the project and installing the dependencies.

# Clone the repository
git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

# Install dependencies
uv install -e .

Grant Full Disk Access to your terminal or to Claude Desktop/Cursor so the MCP can read the Messages database.

System Preferences/Settings > Security & Privacy/Privacy > Full Disk Access

Integration and configuration

Configure clients to connect to the MCP server. The following example shows a JSON-style configuration you would wire into a client, enabling the server to run under the standard MCP runtime.

Claude Desktop integration creates a standard stdio-based MCP server entry that launches the MCP when Claude starts.

{
  "mcpServers": {
    "messages": {
      "command": "uvx",
      "args": [
        "mac-messages-mcp"
      ]
    }
  }
}

Security notes

This application accesses the Messages database, which contains personal communications. Use it responsibly and ensure you have the proper permissions to access and manage messages on your device.

Usage as a module

You can import the library in Python to read recent messages and send messages through a simple API.

from mac_messages_mcp import get_recent_messages, send_message

# Get recent messages
messages = get_recent_messages(hours=48)
print(messages)

# Send a message (automatic delivery method)
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)

Usage as a CLI tool

Run the MCP server directly from the command line.

mac-messages-mcp

Available tools

get_recent_messages

Retrieve recent messages from the macOS Messages app within a specified time window.

send_message

Send a message to a recipient. The server automatically chooses iMessage or SMS/RCS based on availability.

check_imessage_availability

Check if a recipient has iMessage available before sending.