Automate macOS Messages for Universal Communication

Mac Messages MCP

Read, search, and send macOS Messages from any local MCP client.

Quick start · Available tools · Agent skill · Command-line interface · Security · Changelog

Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and send messages through the macOS Messages app.

Mac Messages MCP runs locally on your Mac. It opens the Messages and Contacts databases read-only, returns only the data a client asks for, and uses Messages.app automation only when the client explicitly calls the send tool.

How it works

flowchart LR
    A[MCP client] -->|stdio| B[mac-messages-mcp]
    B --> C{Tool call}
    C -->|read tools| D[(chat.db read-only)]
    C -->|read tools| E[(AddressBook read-only)]
    C -->|send tools| F[Messages.app]
    F --> G[Recipient]
    D --> H[Untrusted-output boundary]
    E --> H
    H --> A

Everything the client reads comes from the local SQLite databases, opened read-only. Everything that leaves the machine goes out through Messages.app, under an explicit send tool call. Message- and contact-derived text is fenced as untrusted data on the way back to the model.

Capabilities

Quick start

1. Install uv

brew install uv

Confirm that the launcher is available:

uvx --version

Python 3.10 or newer is required. uvx can provision a compatible Python and installs Mac Messages MCP in an isolated environment, so you do not need to create a virtual environment first.

2. Grant macOS permissions

Open System Settings → Privacy & Security → Full Disk Access and enable the app that will launch the MCP server:

• Claude Desktop, Cursor, VS Code, or the ChatGPT desktop app when configured in that app
• Terminal, iTerm2, Ghostty, or another terminal when using Claude Code or Codex CLI from that terminal

Quit and reopen the app after changing Full Disk Access. On the first contact lookup or send, macOS may separately ask for access to Contacts or permission to control Messages. Allow those prompts.

Also make sure Messages.app is open, signed in, and already able to send a normal message.

3. Add the server to your MCP client

The server command is the same everywhere:

uvx mac-messages-mcp

Choose your client below.

Claude Desktop

Open Claude → Settings → Developer → Edit Config, then add:

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

Preserve any other servers already in claude_desktop_config.json, save the file, and restart Claude Desktop.

Claude Desktop also supports installable .mcpb extensions. See Build the Claude Desktop extension if you want to package this repository as one.

Claude Code

Add it once at user scope so it is available in every project:

claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcp

Verify it:

claude mcp get mac-messages

Inside Claude Code, run /mcp to inspect the connection and tools.

Codex CLI, Codex IDE extension, and ChatGPT desktop app

Codex clients on the same Mac share MCP configuration. Add the server with:

codex mcp add mac-messages -- uvx mac-messages-mcp

Then verify it:

codex mcp list

You can also add it directly to ~/.codex/config.toml:

[mcp_servers.mac-messages]
command = "uvx"
args = ["mac-messages-mcp"]

Restart the desktop app or IDE extension after changing the configuration. In Codex CLI, use /mcp to view the active server.

Cursor

Or open Cursor Settings → Tools & MCP → New MCP Server and use:

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

Restart the server from Cursor's MCP settings after saving.

VS Code / GitHub Copilot

Open the Command Palette and run MCP: Add Server. Choose Command (stdio), enter uvx as the command, add mac-messages-mcp as the argument, and install it globally.

Or add it from a terminal:

code --add-mcp '{"name":"mac-messages","command":"uvx","args":["mac-messages-mcp"]}'

The equivalent user or workspace mcp.json entry is:

{
  "servers": {
    "mac-messages": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

Other stdio MCP clients

Use this generic server definition:

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

If a GUI client reports that uvx cannot be found, run which uvx in Terminal and replace "uvx" with the returned absolute path. Homebrew commonly installs it at /opt/homebrew/bin/uvx on Apple silicon and /usr/local/bin/uvx on Intel Macs.

4. Verify the connection

Ask your client to call tool_check_db_access, then tool_check_addressbook. Once both succeed, try prompts such as:

Show me my messages from the last two hours.

Find messages from Carter about dinner in the last 30 days.

Find PDFs sent to me this month, but do not open any yet.

Find Jordan in my contacts and draft a message saying I am running 10 minutes
late. Do not send it until I confirm.

The first uvx launch can take longer while it downloads and caches Python dependencies.

5. Optional: set the phone number region

Phone numbers written in national format (06 39 98 00 01, (415) 555-1234) have to be expanded to E.164 before they can be matched against the Messages database, and that expansion needs to know which country they belong to. The server reads your Mac's own region setting for this, so on a correctly configured Mac there is nothing to do.

Set MAC_MESSAGES_REGION to an ISO 3166-1 alpha-2 code when your numbers belong to a different region than your Mac is configured for - a French SIM on a Mac set to en_US, say:

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

For Claude Code:

claude mcp add --transport stdio --scope user \
  --env MAC_MESSAGES_REGION=FR \
  mac-messages -- uvx mac-messages-mcp

The region is resolved once at startup, so restart the server after changing it. Resolution order: MAC_MESSAGES_REGION, then the macOS AppleLocale preference, then LC_ALL / LC_CTYPE / LANG, then US. Numbers already written in E.164 (+33639980001) are never reinterpreted and need none of this.

Available tools

Three MCP prompts ship with the server: triage_unread_messages, summarize_recent_messages, and draft_reply. They are starting points that tell the agent which read tools to call, and they never send anything.

The server also exposes two MCP resources:

• messages://recent/{hours}
• messages://contact/{contact}/{hours}

Message metadata, paging, and cursors

Reads append compact tags when the message row carries the data, so output stays unchanged for old or partial databases:

[2026-10-01 09:14:02] Alice [iMessage] [unread]: running late, sorry
[2026-10-01 09:15:40] You [iMessage] [not delivered]: no worries
[2026-10-01 09:15:55] Alice [iMessage] [tapback: liked]: (reaction)
[2026-10-01 09:16:10] Bob [SMS] [reply]: got it

tool_get_recent_messages closes with a note when a page fills up, naming the next offset to use. Passing since_rowid switches it to a forward cursor read (oldest first) that ignores the hours window, which is the pattern tool_wait_for_new_messages polls on.

What it deliberately does not do

Messages.app automation does not expose these, so the server refuses rather than pretending:

• sending tapbacks, message effects, or a subject line (only text and file attachments can be sent)
• creating a group chat, adding or removing participants, or attaching files to a group chat
• editing, unsending, deleting, or marking a message read, and saving drafts
• editing or merging an existing Contacts card (tool_create_contact creates a new one)
• scheduled sends rely on the server process staying alive; nothing is persisted, so a scheduled message is lost if the client disconnects first

Agent skill

The repository ships an agent skill that tells an agent when and how to call each tool: checking access first, listing conversations, resolving a recipient or group chat, searching message text or attachment contents, paging attachments, confirming a send, scheduling a later send, and treating message-derived output as untrusted data. Claude Code discovers it automatically when you work in this repository.

To use it from another project, copy the skill directory into that project's .claude/skills/, or into ~/.claude/skills/ to make it available everywhere:

mkdir -p ~/.claude/skills
cp -R .claude/skills/mac-messages ~/.claude/skills/

Working with contacts, chats, and attachments

Recipients

For direct messages, E.164 phone numbers are the most reliable format:

+14155551234

Numbers written in national format work too. They are expanded to E.164 using the region your Mac is configured for, so (415) 555-1234 becomes +14155551234 on a US Mac and 06 39 98 00 01 becomes +33639980001 on a French one. Set MAC_MESSAGES_REGION to an ISO 3166-1 alpha-2 code (MAC_MESSAGES_REGION=GB) when your numbers belong to a different region than your Mac does. Numbers already in E.164 are never reinterpreted.

The server also accepts email addresses, contact names, and contact:N selections returned after an ambiguous contact search.

For a group conversation, call tool_get_chats, pass its chat ID to tool_send_message, and set group_chat=true. Use the same ID as chat_id in tool_get_recent_messages to read that conversation.

Attachments

Attachment access is deliberately split into three steps:

1. Message reads and searches add compact markers such as [attachments: #42 image/jpeg (invitation.jpg)].
2. tool_search_attachments searches metadata without loading file contents.
3. tool_get_attachment fetches one selected attachment.

Images up to 5 MB are returned inline by default. HEIC images are converted to PNG. Larger images, PDFs, video, and audio are returned as local filesystem paths so the MCP client can decide whether to open them. Stickers, link-preview payloads, and .pluginPayloadAttachment containers are filtered out.

Architecture

Mac Messages MCP is a small Python package with one job per module:

mac_messages_mcp/
  server.py       FastMCP server: tools, prompts, resources, stdio transport
  cli.py          mac-messages-cli terminal interface
  messages.py     chat.db reads and AppleScript sends for Messages.app
  content.py      Best-effort text/PDF attachment content search
  phone.py        E.164 normalization against the Mac's configured region
  scheduler.py    In-process scheduled-send queue
  untrusted.py    Structural neutralization of Messages/Contacts-derived text
scripts/
  build_mcpb.py   Builds the Claude Desktop .mcpb extension
  bump_version.py Keeps version metadata in sync across release files
tests/            Pytest suite over temporary databases and mocked AppleScript
main.py           Stdio entry point for MCP clients
manifest.json     MCPB manifest for the Claude Desktop extension

Reads go straight to chat.db and the AddressBook database; sends go through AppleScript into Messages.app. Model-facing payloads pass through untrusted.py before they reach the client.

Troubleshooting

uvx or spawn uvx ENOENT

The GUI app cannot see your shell's Homebrew path. Run:

which uvx

Use that full path as the MCP command, then restart the client.

Operation not permitted, unable to open database file, or no messages

Grant Full Disk Access to the app that launches the server, not just to Messages.app. Completely quit and reopen the launcher afterward, then call tool_check_db_access again.

For Claude Code or Codex CLI, the launcher is normally your terminal. For a desktop or IDE integration, it is normally Claude Desktop, Cursor, VS Code, or the ChatGPT desktop app itself.

Contacts are empty or contact lookup fails

Allow the launching app to access Contacts if macOS prompts. Confirm Full Disk Access, restart the app, and call tool_check_addressbook followed by tool_check_contacts.

If contacts are listed but their numbers carry the wrong country code, the server is expanding your national-format numbers against the wrong region. Set MAC_MESSAGES_REGION to the right ISO 3166-1 alpha-2 code and restart the server.

Reading works but sending fails

1. Open Messages.app and send a message manually to confirm the account and recipient work.
2. Check System Settings → Privacy & Security → Automation and allow the launching app to control Messages.
3. Prefer an E.164 number such as +14155551234 for a direct recipient.
4. Use tool_check_imessage_availability to inspect the likely route.

An attachment is listed but cannot be opened

Messages may retain database metadata after macOS has offloaded the file. Open the conversation in Messages.app and download the attachment, then retry tool_get_attachment.

The server appears to hang when run in Terminal

That is normal for an MCP stdio server: it waits for protocol input from a client. Use your client's MCP status view, or launch the MCP Inspector:

yarn dlx @modelcontextprotocol/inspector uvx mac-messages-mcp

Install as a standalone tool

MCP clients can launch the package directly with uvx; a permanent installation is optional.

uv tool install mac-messages-mcp
mac-messages-mcp

Upgrade or remove it with:

uv tool upgrade mac-messages-mcp
uv tool uninstall mac-messages-mcp

Python API

The MCP server is the primary interface, but the package also exports its core read/send functions:

from mac_messages_mcp import get_recent_messages, send_message

recent = get_recent_messages(hours=48)
print(recent)

result = send_message(
    recipient="+14155551234",
    message="Hello from Mac Messages MCP!",
)
print(result)

These calls use the same macOS permissions and can send real messages.

Command-line interface

The package also installs a mac-messages-cli command, so Messages can be read, searched, and sent from a terminal without an MCP client. It uses the same local databases and needs the same macOS permissions as the server; granting Full Disk Access to your terminal covers both.

uv tool install mac-messages-mcp
mac-messages-cli --help

# Last 48 hours, or one contact, or one group chat
mac-messages-cli recent -n 48
mac-messages-cli recent --contact "Jordan"
mac-messages-cli recent --chat chat721054478304420871

# Fuzzy search: last 30 days by default, or all history with -n 0
mac-messages-cli search "dinner" -t 0.7
mac-messages-cli search "dinner" -n 0

# Contacts and group chats
mac-messages-cli contact "Jordan"
mac-messages-cli chats

# Attachments: search metadata, then fetch or save one file
mac-messages-cli attachments --since 2026-09-01 --mime image/ --limit 20
mac-messages-cli attachment 42 --save ~/Desktop/invitation.jpg

# Permissions and iMessage reachability
mac-messages-cli check --recipient +14155551234

# Sending prompts for confirmation unless --yes is passed
mac-messages-cli send +14155551234 "Running 10 minutes late."

mac-messages-cli send asks for y/N confirmation before sending. When stdin is not a terminal it refuses to send unless --yes is passed, so an unattended script cannot send a message by accident. Commands exit non-zero when a lookup fails, so the output is safe to branch on in scripts.

Development

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

uv sync --frozen --extra dev
uv run pytest
uv run black --check .
uv run isort --check-only .
uv build

Tests mock AppleScript and use temporary database fixtures; they must never read a contributor's real Messages or Contacts data. See CONTRIBUTING.md for the contribution checklist and VERSIONING.md for releases.

Build the Claude Desktop extension

The repository includes an MCPB manifest.json and a build script that can bundle an architecture-specific uv binary:

yarn global add @anthropic-ai/mcpb
uv run python scripts/build_mcpb.py

For an Intel build:

uv run python scripts/build_mcpb.py --arch x86_64

Install the generated .mcpb from Claude Desktop → Settings → Extensions → Advanced settings → Install Extension…. A bundled extension still needs network access on first launch to download Python and the package dependencies.

Use --no-bundle to package against the system uv, or run uv run python scripts/build_mcpb.py --help for every option.

Docker

The included Dockerfile is for package and catalog validation. A Linux container cannot access macOS TCC permissions or automate Messages.app, so Docker is not a supported way to read or send messages on the host Mac.

Documentation

scripts/build_mcpb.py

#!/usr/bin/env python3
# Copyright (c) 2023 Carter Lasalle
"""Build script for the Mac Messages MCP Claude Desktop extension (.mcpb).

Vendors a `uv` binary into the bundle so the packaged extension runs on
machines that don't have `uv` installed, then runs `mcpb pack`.

Usage:
    python scripts/build_mcpb.py [--arch arm64|x86_64]
        [--uv-version X.Y.Z] [--no-bundle]
    python scripts/build_mcpb.py --help

Options:
    --arch         Target architecture (defaults to the host architecture).
    --uv-version   uv release to vendor (default: pinned known-good version).
    --no-bundle    Pack against the system `uv` without vendoring a binary.

The vendored `uv` binary is architecture specific, so build one .mcpb per
architecture you need to support. On first launch the bundled `uv` still
downloads Python and dependencies, so network access is required once.
"""

import hashlib
import http.client
import json
import platform
import shutil
import subprocess
import sys
import tarfile
import tempfile
from pathlib import Path
from urllib.parse import urljoin, urlparse

# Pinned uv release for reproducible builds; override with --uv-version.
DEFAULT_UV_VERSION = "0.11.19"
UV_DOWNLOAD_PREFIX = "https://github.com/astral-sh/uv/releases/download/"
UV_DOWNLOAD_URL = UV_DOWNLOAD_PREFIX + "{version}/{asset}.tar.gz"
_ALLOWED_DOWNLOAD_HOSTS = frozenset(
    {
        "github.com",
        "objects.githubusercontent.com",
        "github-releases.githubusercontent.com",
        "release-assets.githubusercontent.com",
    },
)
_DOWNLOAD_TIMEOUT_SECONDS = 60
_MAX_DOWNLOAD_REDIRECTS = 8

# Map architecture aliases to uv's macOS release asset names.
ARCH_ASSETS = {
    "arm64": "uv-aarch64-apple-darwin",
    "aarch64": "uv-aarch64-apple-darwin",
    "x86_64": "uv-x86_64-apple-darwin",
    "intel": "uv-x86_64-apple-darwin",
}

BIN_DIR = Path("bin")
MANIFEST_PATH = Path("manifest.json")
BUNDLED_COMMAND = "${__dirname}/bin/uv"


def print_help():
    """Print help information."""
    print(__doc__)
    sys.exit(0)


def resolve_asset(arch):
    """Map an architecture alias to uv's release asset name."""
    key = (arch or platform.machine()).lower()
    asset = ARCH_ASSETS.get(key)
    if asset is None:
        valid = ", ".join(sorted(set(ARCH_ASSETS)))
        print(f"Error: unsupported arch '{key}'. Choose from: {valid}")
        sys.exit(1)
    return asset


def download(url):
    """Download a GitHub uv release URL and return the raw bytes.

    Raises
    ------
    ValueError
        If ``url`` is not a pinned uv release URL.

    """
    if not url.startswith(UV_DOWNLOAD_PREFIX):
        msg = f"refusing to download untrusted URL: {url}"
        raise ValueError(msg)
    print(f"Downloading {url}")
    return _https_get_allowlisted(url)


def _https_get_allowlisted(url):
    """GET `url` over HTTPS, following redirects only to known GitHub hosts.

    Raises
    ------
    ValueError
        If a URL is not an allowlisted HTTPS GitHub host, the response is not
        a redirect or 200, or the redirect limit is exceeded.

    """
    current = url
    for _ in range(_MAX_DOWNLOAD_REDIRECTS):
        parsed = urlparse(current)
        if (
            parsed.scheme != "https"
            or not parsed.hostname
            or parsed.hostname not in _ALLOWED_DOWNLOAD_HOSTS
        ):
            msg = f"refusing to download untrusted URL: {current}"
            raise ValueError(msg)
        path = parsed.path or "/"
        if parsed.query:
            path = f"{path}?{parsed.query}"
        connection = http.client.HTTPSConnection(
            parsed.hostname,
            timeout=_DOWNLOAD_TIMEOUT_SECONDS,
        )
        try:
            connection.request(
                "GET",
                path,
                headers={"User-Agent": "mac-messages-mcp-mcpb-builder"},
            )
            response = connection.getresponse()
            if response.status in {301, 302, 303, 307, 308}:
                location = response.getheader("Location")
                response.read()
                if not location:
                    msg = f"redirect without Location from {current}"
                    raise ValueError(msg)
                current = urljoin(current, location)
                continue
            if response.status != 200:
                msg = f"download failed: HTTP {response.status} for {current}"
                raise ValueError(
                    msg,
                )
            return response.read()
        finally:
            connection.close()
    msg = f"too many redirects downloading {url}"
    raise ValueError(msg)


def vendor_uv(asset, version):
    """Download, checksum-verify, and extract the uv binary into bin/uv."""
    url = UV_DOWNLOAD_URL.format(version=version, asset=asset)
    archive = download(url)

    expected = download(url + ".sha256").decode().split()[0]
    actual = hashlib.sha256(archive).hexdigest()
    if actual != expected:
        print("Error: checksum mismatch for uv download")
        print(f"  expected: {expected}")
        print(f"  actual:   {actual}")
        sys.exit(1)
    print("Checksum verified")

    BIN_DIR.mkdir(exist_ok=True)
    uv_path = BIN_DIR / "uv"
    with tempfile.TemporaryDirectory() as tmp:
        tar_path = Path(tmp) / "uv.tar.gz"
        tar_path.write_bytes(archive)
        with tarfile.open(tar_path) as tar:
            source = tar.extractfile(f"{asset}/uv")
            uv_path.write_bytes(source.read())
    uv_path.chmod(0o755)
    print(f"Vendored uv {version} ({asset}) -> {uv_path}")


def mcpb_cli():
    """Return the command used to invoke the mcpb CLI."""
    if shutil.which("mcpb"):
        return ["mcpb"]
    return ["npx", "--yes", "@anthropic-ai/mcpb"]


def pack(bundle):
    """Run `mcpb pack`, temporarily pointing the manifest at the bundled uv.

    The tracked manifest.json is always restored afterwards so the default
    system-uv flow stays unchanged.
    """
    original = MANIFEST_PATH.read_text(encoding="utf-8")
    try:
        if bundle:
            manifest = json.loads(original)
            manifest["server"]["mcp_config"]["command"] = BUNDLED_COMMAND
            MANIFEST_PATH.write_text(
                json.dumps(manifest, indent=2) + "\n",
                encoding="utf-8",
            )
            print(f"manifest command -> {BUNDLED_COMMAND}")
        subprocess.run([*mcpb_cli(), "pack"], check=True, shell=False)
    finally:
        MANIFEST_PATH.write_text(original, encoding="utf-8")
        if bundle:
            print("Restored manifest.json")


def main():
    args = sys.argv[1:]
    if any(a in {"-h", "--help", "help"} for a in args):
        print_help()

    arch = None
    uv_version = DEFAULT_UV_VERSION
    bundle = True

    i = 0
    while i < len(args):
        arg = args[i]
        if arg == "--arch":
            i += 1
            if i >= len(args):
                print("Error: --arch requires a value")
                sys.exit(1)
            arch = args[i]
        elif arg == "--uv-version":
            i += 1
            if i >= len(args):
                print("Error: --uv-version requires a value")
                sys.exit(1)
            uv_version = args[i]
        elif arg == "--no-bundle":
            bundle = False
        else:
            print(f"Error: unknown argument '{arg}'")
            print(
                "Usage: python scripts/build_mcpb.py [--arch arm64|x86_64] "
                "[--uv-version X.Y.Z] [--no-bundle]",
            )
            sys.exit(1)
        i += 1

    if sys.platform != "darwin":
        print("Warning: mac-messages-mcp targets macOS; building on a non-macOS host.")

    if bundle:
        asset = resolve_asset(arch)
        vendor_uv(asset, uv_version)
    else:
        print("Packing against system uv (no vendored binary).")

    pack(bundle)
    print("Done.")


if __name__ == "__main__":
    main()