Mac Messages MCP

Name: Mac Messages MCP
Author: carterlasalle

@carterlasalle

Mac Messages MCP について

An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to query and analyze iMessage conversations. It includes robust phone number validation, attachment processing, contact management, group chat handling, and full

#macos #mac #applescript #contacts #mcp #cursor #imessage #claude #mcp-server

基本情報

カテゴリ

その他

ライセンス

MIT

ランタイム

python

トランスポート

stdio

公開者

carterlasalle

投稿者

Carter LaSalle

設定

以下の設定を使って、このサーバーを MCP 対応クライアントに追加してください。

{
  "mcpServers": {
    "mac_messages_mcp": {
      "command": "python",
      "args": [
        "scripts/build_mcpb.py",
        "#",
        "build",
        "for",
        "the",
        "host",
        "architecture"
      ]
    }
  }
}

ツール

ツールは検出されませんでした

ツールは README から自動的に抽出されます。メンテナーは ## Tools という見出しの下に記載することで、このタブに反映できます。

概要

What is Mac Messages MCP?

Mac Messages MCP is a Python bridge for interacting with the macOS Messages app using the Model Context Protocol (MCP). It enables sending and reading iMessages and SMS/RCS messages, and searching attachments, designed for macOS users who want programmatic access to their Messages database.

How to use Mac Messages MCP?

Install via uvx mac-messages-mcp (requires macOS 11+, Python 3.10+, and the uv package manager). Grant Full Disk Access to your terminal or app. Integrate with Claude Desktop by adding a config with command uvx mac-messages-mcp or with Cursor by pasting uvx mac-messages-mcp in MCP settings. For Docker, use mcp-proxy to bridge stdio to HTTP.

Key features of Mac Messages MCP

Universal message sending (iMessage or SMS/RCS based on recipient availability)
Smart fallback to SMS when iMessage is unavailable
Read recent messages from the macOS Messages app
Filter messages by contact or phone number
Group chat filtering using chat IDs
Fuzzy search through message content
Attachment discovery and fetching (progressive disclosure)
iMessage availability checking before sending

Use cases of Mac Messages MCP

Automatically send iMessages or SMS to contacts without manual switching
Read and search recent conversations programmatically
Find and view photos, PDFs, or other attachments shared in chats
Filter messages by a specific contact or group chat ID
Check whether a recipient can receive iMessages before sending

FAQ from Mac Messages MCP

What are the prerequisites for Mac Messages MCP?

macOS 11+, Python 3.10+, the uv package manager, and Full Disk Access permission for the terminal or application running the server.

How do I install Mac Messages MCP?

Run uvx mac-messages-mcp in your terminal, or install from PyPI with uv pip install mac-messages-mcp. For source installation, clone the repo and run uv install -e ..

Does Mac Messages MCP work inside Docker?

Messages.app automation is macOS‑only, so the server itself does not work inside a Linux container. The Dockerfile is for catalog checks and read‑only database experiments with mounted data. To connect from a container, run mcp-proxy on the host to bridge stdio to HTTP.

How are attachments handled?

Attachments use progressive disclosure: message searches show a compact summary, an attachment‑first search returns metadata, and fetching returns the file. Images are returned inline (HEIC converted to PNG), while PDFs, video, and audio return a filesystem path. Inline image bytes are capped at 5MB by default.

What message formats are supported for recipients?

E.164 phone numbers with a leading + (e.g., +14155551234) are most reliable. Bare digit numbers are normalized, and 10‑digit US numbers are sent as +1.... The tool_find_contact returns phone matches in send‑ready format.