Mac Messages MCP
Python bridge for macOS Messages via Model Context Protocol.
Key Features
Use Cases
README
Mac Messages MCP
A Python bridge for interacting with the macOS Messages app using MCP (Multiple Context Protocol).
Quick Install
For Cursor Users
Click the button above to automatically add Mac Messages MCP to Cursor
For Claude Desktop Users
See the Integration section below for setup instructions.
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)
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.
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Star History
Star History
Repository Owner
User
Repository Details
Programming Languages
Tags
Topics
Join Our Newsletter
Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.
Related MCPs
Discover similar Model Context Protocol servers
iMessage Query MCP Server
Securely query and analyze your iMessage history with LLMs using the Model Context Protocol.
iMessage Query MCP Server is an MCP-compliant server that provides safe access to the macOS iMessage database for Large Language Models (LLMs). Built with the FastMCP framework and imessagedb library, it enables querying, validation, and analysis of iMessage conversations, complete with proper phone number handling and permissions management. The tool integrates seamlessly with MCP clients such as Claude Desktop and CLine for VSCode, allowing for controlled retrieval of chat histories via standardized protocols. Enhanced security features and automated dependency management ensure a smooth and safe user experience.
- ⭐ 71
- MCP
- hannesrudolph/imessage-query-fastmcp-mcp-server
iMessage MCP
MCP server enabling LLM integration with macOS iMessage data.
iMessage MCP offers a Model Context Protocol (MCP) server that facilitates seamless integration between large language models (LLMs) and macOS iMessage data. It provides robust tools for searching and managing iMessage messages, conversations, and contacts in a read-only manner. Features include message and contact search, chat listing, and context retrieval, making it suitable for conversational agents and context-aware applications. Built using Deno and designed for easy integration with applications such as Claude Desktop, it handles context management efficiently for AI models.
- ⭐ 16
- MCP
- wyattjoh/imessage-mcp
MCP Server for Milvus
Bridge Milvus vector database with AI apps using Model Context Protocol (MCP).
MCP Server for Milvus enables seamless integration between the Milvus vector database and large language model (LLM) applications via the Model Context Protocol. It exposes Milvus functionality to external LLM-powered tools through both stdio and Server-Sent Events communication modes. The solution is compatible with MCP-enabled clients such as Claude Desktop and Cursor, supporting easy access to relevant vector data for enhanced AI workflows. Configuration is flexible through environment variables or command-line arguments.
- ⭐ 196
- MCP
- zilliztech/mcp-server-milvus
WhatsApp MCP Server
Bridge WhatsApp messaging to Model Context Protocol-compliant LLM agents.
WhatsApp MCP Server enables users to access, search, and interact with their personal WhatsApp messages through the Model Context Protocol. It connects to WhatsApp via the WhatsApp web multidevice API, stores messages locally in a SQLite database, and exposes them as tools to LLM-powered agents like Claude. Users can also send messages, media, and search contacts, all while retaining control over what is shared with the AI agent.
- ⭐ 5,056
- MCP
- lharries/whatsapp-mcp
Homebrew MCP Python Server
Expose Homebrew management as MCP tools for integration with AI clients.
Homebrew MCP Python Server provides an MCP-compliant interface to manage Homebrew packages on macOS via a Python-based server. It enables standardized control of Homebrew commands through the Model Context Protocol, supporting integration with Claude Desktop, Cursor, and other MCP-compatible clients. The server operates via stdio using JSON-RPC 2.0, logs all interactions, and offers a declarative Python implementation. It is designed for seamless tool-chaining, advanced context management, and easy integration into LLM-driven environments.
- ⭐ 18
- MCP
- jeannier/homebrew-mcp
Everything Search MCP Server
Fast, cross-platform file search via Model Context Protocol integration.
Everything Search MCP Server provides fast file and folder search capabilities across Windows, macOS, and Linux platforms as an MCP server. It leverages native search utilities such as the Everything SDK on Windows, mdfind on macOS, and locate/plocate on Linux. The tool exposes a standardized search interface with customizable parameters including query, sorting, and matching options. It is suitable for integration with AI clients or automation tools that follow the Model Context Protocol.
- ⭐ 268
- MCP
- mamertofabian/mcp-everything-search
Didn't find tool you were looking for?