mac_messages_mcp

Mac Messages MCP exposes a Python-based MCP server that bridges the macOS Messages app to external tools via the UV (MCP) protocol. It enables sending messages (via iMessage when available and falling back to SMS/RCS for non-iMessage recipients), reading recent conversations, and checking delivery capabilities (such as iMessage availability) before sending. The server is designed to be consumed through the UV/uvx workflow, making it straightforward to connect with Claude Desktop, Cursor, or a proxy layer for Docker deployments. Typical usage involves starting the MCP server with uvx mac-messages-mcp and then interacting with the server through your preferred integration point or through provided Python module entry points for sending and querying messages.

Prerequisites:

• macOS (tested on macOS 11+)
• Python 3.10+
• uv package manager

Install uv (if not already installed):

# macOS
brew install uv

Install the MCP server from PyPI:

uv pip install mac-messages-mcp

Or install from source:

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

# Install dependencies
uv install -e .

Run the MCP server directly (requires macOS and Full Disk Access as described in the README):

uvx mac-messages-mcp

Note: If you need remote access or containerized usage, consider using the mcp-proxy bridge described in the Docker integration section of the README to expose the server over HTTP for Docker-based clients.

Tips and notes:

• This MCP server accesses the macOS Messages database; ensure you grant Full Disk Access to your terminal or the app running the MCP server.
• Only run one MCP server instance at a time per environment (do not run multiple instances via Cursor and Claude Desktop simultaneously).
• For Docker or remote usage, you can bridge this uvx-based server with mcp-proxy to expose an HTTP API accessible from other containers or hosts.
• In macOS, iMessage availability can vary by recipient; use the check_imessage_availability helper to decide whether to attempt iMessage or fall back to SMS/RCS.
• When integrating with other tools, prefer the provided uvx invocation: uvx mac-messages-mcp, which launches the Python-based server via UV.
• If you run into port/host binding issues when using proxies, ensure the proxy is configured to forward /mcp correctly and that network ACLs allow the relevant ports.