Happy slice of mcp pizzaMCP.pizza
Fire in da houseTop Tip:Most people pay up to $340 per month for Perplexity, MidJourney, Runway, ChatGPT, and more - but you can get them all your AI tools for $15 with Galaxy. It's free to test!Fire in da houseCheck it out

mac_messages_mcp

MCP.Pizza Chef: carterlasalle

mac_messages_mcp is an MCP server that provides secure, structured access to the macOS Messages app database. It enables LLMs to query, analyze, and interact with iMessage conversations, including message reading, sending, contact management, and group chat handling. It supports phone number validation and attachment processing, making it a comprehensive bridge for iMessage integration via the Model Context Protocol on macOS systems.

Use This MCP server To

Query and analyze iMessage conversations via LLMs Send new iMessages programmatically through MCP Filter and retrieve messages by contact or group chat Process and manage message attachments securely Validate phone numbers within iMessage workflows Integrate iMessage data into AI-enhanced applications Access macOS Messages app data through a standardized API

README

Mac Messages MCP

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

PyPI Downloads

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

Verified on MseeP

Features

  • Read recent messages from the macOS Messages app
  • Filter messages by contact
  • Send new messages through iMessage
  • Access messages via an API

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:

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

Integration

Claude Desktop Integration

  1. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json
  2. Add the following configuration:
{
    "mcpServers": {
        "messages": {
            "command": "uvx",
            "args": [
                "mac-messages-mcp"
            ]
        }
    }
}

Cursor Integration

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

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

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
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)

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.

MseeP.ai Security Assessment Badge

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Star History

Star History Chart

mac_messages_mcp FAQ

How do I install mac_messages_mcp on my Mac?
You need macOS 11 or later, Python 3.10+, and the uv package manager, which can be installed via Homebrew.
Can mac_messages_mcp send new messages through iMessage?
Yes, it fully supports sending new messages via the macOS Messages app.
Does mac_messages_mcp support group chats?
Yes, it includes full support for managing and querying group chat conversations.
How does mac_messages_mcp handle phone number validation?
It includes robust phone number validation to ensure accurate contact identification and message routing.
Is attachment processing supported by mac_messages_mcp?
Yes, it can process and manage attachments within iMessage conversations securely.
What programming language is mac_messages_mcp built with?
It is implemented as a Python bridge for macOS Messages app interaction.
Can I filter messages by contact using mac_messages_mcp?
Yes, it allows filtering and retrieving messages by specific contacts.
Is mac_messages_mcp compatible with other LLM providers besides OpenAI?
Yes, it is designed to work with multiple LLM providers like OpenAI, Anthropic Claude, and Google Gemini.