Back to MCP Servers

iMessages MCP MCP Server

A community MCP server that reads from and sends messages through the macOS Messages app, with automatic iMessage/SMS routing.

Desktop Automation by carterlasalle (community) None active
GitHub Docs
Overview

Mac Messages MCP is a Python bridge for interacting with the macOS Messages app over the Model Context Protocol. It lets an LLM read recent messages from the local Messages database, search conversations and attachments, look up contacts, and send new messages through the Messages app. Routing between iMessage and SMS/RCS happens automatically based on what the recipient supports.

The server combines direct SQLite reads of the Messages database (~/Library/Messages/chat.db) with AppleScript automation for sending. It exposes tools for fuzzy text search, attachment retrieval (with image conversion to PNG), group chat listing, and phone number validation. No API keys are required: access is gated entirely by macOS Full Disk Access permissions on the terminal or IDE running the server.

This is a community-maintained project, not an official Apple integration. Apple does not publish a Messages API, so all iMessage MCP servers rely on the local database and AppleScript. Among the available options, this one has the broadest feature set (read + send + attachments + contacts + group chats).

Tools

Tool Description
tool_get_recent_messages Retrieve recent messages, optionally filtered by contact or date range.
tool_fuzzy_search_messages Search message content with fuzzy text matching.
tool_send_message Send a message via iMessage or SMS/RCS, with automatic fallback based on recipient platform.
tool_get_chats List group conversations by chat ID.
tool_search_attachments Find attachments by date, contact, or MIME type.
tool_get_attachment Retrieve a file attachment; images are converted to PNG.
tool_find_contact Locate contacts and validate phone numbers (E.164 format preferred).
Setup Guide

Prerequisites

  • macOS 11 (Big Sur) or later
  • Python 3.10+
  • uv package manager (brew install uv)
  • Full Disk Access granted to your terminal or IDE in System Settings, Privacy and Security

Installation

Install from PyPI:

uv pip install mac-messages-mcp

Or from source:

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp
uv install -e .

Claude Desktop config

Add to claude_desktop_config.json:

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

Cursor

Add uvx mac-messages-mcp as an MCP server in Cursor settings, or use the one-click install link in the project README.

Granting Full Disk Access

System Settings, Privacy and Security, Full Disk Access. Add the application that launches the MCP server (Claude Desktop, Cursor, Terminal, iTerm, etc.) and restart it.

Use Cases
  • Triage unread iMessages by asking an agent to summarize recent threads with a specific contact or date range
  • Send templated follow-up texts from automations without opening the Messages app
  • Search years of message history for a quote, link, or address using fuzzy text matching
  • Pull image attachments out of a thread and convert them to PNG for downstream analysis
  • Identify the right phone number/handle for a contact before sending, with E.164 validation
Example Prompts
  • "Show me the last 20 messages I exchanged with Alex this week."
  • "Search my iMessages for the Airbnb address my brother sent me in March."
  • "Send an iMessage to +14155551234 saying I'm running 10 minutes late."
  • "List my active group chats and tell me which ones had activity today."
  • "Find all image attachments from Mom in the last 30 days."
Pros
  • Full read and send support, including automatic iMessage to SMS/RCS fallback
  • No API keys, accounts, or paid services required, purely local
  • Handles attachments, group chats, fuzzy search, and contact validation
  • Installable as a single uvx command for Claude Desktop and Cursor
Limitations
  • macOS only, will not work on Linux or Windows
  • Requires Full Disk Access, which grants broad permissions to the host app
  • Community-maintained, not an official Apple or Anthropic integration
  • README notes a single-instance limitation, run it on either Claude Desktop or Cursor, not both at once
Alternatives