mcp-registry/mac_messages_mcp

    ==================
      
       /// MCP ///
      /// MAC ///
        
    ==================
        
    [server:online]
    [protocol:ready]

mac_messages_mcp

by carterlasalle

Python-based MCP server that lets LLMs read and send iMessage / SMS through the macOS Messages database with smart iMessage/SMS fallback, fuzzy search, contact filtering and a simple CLI.

149
14
Specialized
GitHubWebsiteDocumentation

01

send_message

Send a message to the specified recipient, automatically choosing iMessage or SMS/RCS based on availability

02

get_recent_messages

Retrieve recent messages from the macOS Messages app, optionally limited by a time window

03

check_imessage_availability

Determine whether the given recipient supports iMessage before sending a message

04

mac-messages-mcp

Command-line entry that launches the Mac Messages MCP server

Installation

1. Prerequisites
• macOS 12+ with iMessage enabled.
• Python 3.9 or newer.
• An API token you will share with your LLM (can be any sufficiently random string).
2. Install the package
pip install mac-messages-mcp
3. Create a config file (or export env-vars)
mac_messages_mcp looks for one of the following:
• `~/.mac_messages_mcp.toml` –or– the equivalent environment variables.
Minimal TOML example:
[server] host = "0.0.0.0" # listening interface port = 3333 # listening port auth_token = "YOUR_SECRET_TOKEN" [imessage] chat_db_path = "~/Library/Messages/chat.db" # usually the default path attachment_dir = "~/Library/Messages/Attachments" # optional override
Environment-variable equivalents (take precedence):
• MCP_HOST, MCP_PORT, MCP_AUTH_TOKEN
• IMESSAGE_DB_PATH, IMESSAGE_ATTACHMENT_DIR
4. Start the server
mac-messages-mcp serve # or python -m mac_messages_mcp
The service will expose a JSON/HTTP API on the configured host/port.
5. Give your LLM the endpoint and the `Authorization: Bearer <token>` string so it can call the MCP server.

Documentation

License: MIT License
Updated 7/30/2025