What can you do with this server?

The **Mac Messages MCP server** allows interaction with the macOS Messages app, enabling users to: * **Retrieve Recent Messages**: Fetch messages with optional filtering by contact or time range * **Send Messages**: Send to individuals (via phone number, email, or contact name) or group chats (using chat ID) * **Find Contacts**: Search for contacts by name using fuzzy matching * **List Contacts**: Retrieve available contacts from the address book * **List Group Chats**: Get available group chats in the Messages app * **Diagnose Access Issues**: Check for and troubleshoot database and AddressBook access problems * **API Integration**: Integrate with tools like Claude Desktop or Cursor for messaging workflows

Which integrations are available for this server?

Allows reading and sending messages through the macOS Messages app, with capabilities to filter messages by contact and interact with [iMessage](/mcp/servers/integrations/imessage) conversations. Provides access to the [macOS](/mcp/servers/integrations/macos) Messages database, enabling interaction with the native messaging system on Mac computers.

Mac Messages MCP

A Python bridge for interacting with the macOS Messages app using MCP (Multiple Context Protocol).

PyPI Downloads

Trust Score

a-diagram-of-a-mac-computer-with-the-tex_FvvnmbaBTFeKy6F2GMlLqA_IfCBMgJARcia1WTH7FaqwA

Quick Install

For Cursor Users

Install MCP Server

Click the button above to automatically add Mac Messages MCP to Cursor

For Claude Desktop Users

See the Integration section below for setup instructions.

Related MCP server: iMCP

Features

Universal Message Sending: Automatically sends via iMessage or SMS/RCS based on recipient availability
Smart Fallback: Seamless fallback to SMS when iMessage is unavailable (perfect for Android users)
Message Reading: Read recent messages from the macOS Messages app
Contact Filtering: Filter messages by specific contacts or phone numbers
Fuzzy Search: Search through message content with intelligent matching
iMessage Detection: Check if recipients have iMessage before sending
Cross-Platform: Works with both iPhone/Mac users (iMessage) and Android users (SMS/RCS)

Prerequisites

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

Installing uv

If you're on Mac, install uv using Homebrew:

brew install uv

Otherwise, follow the installation instructions on the uv website.

⚠️ Do not proceed before installing uv

Installation

Full Disk Access Permission

⚠️ This application requires Full Disk Access permission for your terminal or application to access the Messages database.

To grant Full Disk Access:

Open System Preferences/Settings > Security & Privacy/Privacy > Full Disk Access
Click the lock icon to make changes
Add your terminal app (Terminal, iTerm2, etc.) or Claude Desktop/Cursor to the list
Restart your terminal or application after granting permission

Integration

Claude Desktop Integration

Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json
Add the following configuration:

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

Cursor Integration

Option 1: One-Click Install (Recommended)

Install MCP Server

Option 2: Manual Setup

Go to Cursor Settings > MCP and paste this as a command:

uvx mac-messages-mcp

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

Docker Container Integration

If you need to connect to mac-messages-mcp from a Docker container, you'll need to use the mcp-proxy package to bridge the stdio-based server to HTTP.

Setup Instructions

Install mcp-proxy on your macOS host:

npm install -g mcp-proxy

Start the proxy server:

# Using the published version npx mcp-proxy uvx mac-messages-mcp --port 8000 --host 0.0.0.0 # Or using local development (if you encounter issues) npx mcp-proxy uv run python -m mac_messages_mcp.server --port 8000 --host 0.0.0.0

Connect from Docker: Your Docker container can now connect to:

URL: http://host.docker.internal:8000/mcp (on macOS/Windows)
URL: http://<host-ip>:8000/mcp (on Linux)

Docker Compose example:

version: '3.8' services: your-app: image: your-image environment: MCP_MESSAGES_URL: "http://host.docker.internal:8000/mcp" extra_hosts: - "host.docker.internal:host-gateway" # For Linux hosts

Running multiple MCP servers:

# Terminal 1 - Messages MCP on port 8001 npx mcp-proxy uvx mac-messages-mcp --port 8001 --host 0.0.0.0 # Terminal 2 - Another MCP server on port 8002 npx mcp-proxy uvx another-mcp-server --port 8002 --host 0.0.0.0

Note: Binding to 0.0.0.0 exposes the service to all network interfaces. In production, consider using more restrictive host bindings and adding authentication.

Option 1: Install from PyPI

uv pip install mac-messages-mcp

Option 2: 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 .

Usage

Smart Message Delivery

Mac Messages MCP automatically handles message delivery across different platforms:

iMessage Users (iPhone, iPad, Mac): Messages sent via iMessage
Android Users: Messages automatically fall back to SMS/RCS
Mixed Groups: Optimal delivery method chosen per recipient

# Send to iPhone user - uses iMessage send_message("+1234567890", "Hey! This goes via iMessage") # Send to Android user - automatically uses SMS send_message("+1987654321", "Hey! This goes via SMS") # Check delivery method before sending check_imessage_availability("+1234567890") # Returns availability status

As a Module

from mac_messages_mcp import get_recent_messages, send_message # Get recent messages messages = get_recent_messages(hours=48) print(messages) # Send a message (automatically chooses iMessage or SMS) result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!") print(result) # Shows whether sent via iMessage or SMS

As a Command-Line Tool

# Run the MCP server directly mac-messages-mcp

Development

Versioning

This project uses semantic versioning. See VERSIONING.md for details on how the versioning system works and how to release new versions.

To bump the version:

python scripts/bump_version.py [patch|minor|major]

Security Notes

This application accesses the Messages database directly, which contains personal communications. Please use it responsibly and ensure you have appropriate permissions.

mac-messages-mcp