Labsco
carterlasalle logo

Mac Messages MCP

★ 299

from carterlasalle

A Python bridge for interacting with the macOS Messages app.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#database#devops#git#security

Mac Messages MCP

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

Features

  • Universal Message Sending: Automatically sends via iMessage or SMS/RCS based on recipient availability

  • Smart Fallback: Seamless fallback to SMS when iMessage is unavailable (perfect for Android users)

  • Message Reading: Read recent messages from the macOS Messages app

  • Contact Filtering: Filter messages by specific contacts or phone numbers

  • Group Chat Filtering: Use chat IDs from tool_get_chats to read one group conversation chronologically

  • Fuzzy Search: Search through message content with intelligent matching

  • Attachments: Find and view photos, PDFs, and other attachments shared in conversations

  • iMessage Detection: Check if recipients have iMessage before sending

  • Cross-Platform: Works with both iPhone/Mac users (iMessage) and Android users (SMS/RCS)

Working with attachments

Attachment access uses progressive disclosure — discovery is cheap, fetching is deliberate:

  • Tier 1 — discovery in message search. tool_get_recent_messages and tool_fuzzy_search_messages annotate messages that have attachments with a compact summary like [attachments: #42 image/jpeg (invitation.jpg)]. The id lets you fetch the file later.

  • Tier 2 — attachment-first search. tool_search_attachments(start_date, end_date, contact, mime_type, limit) returns metadata only (id, MIME type, filename, size, sender) — useful for "find all images Elizabeth sent in April 2026" without scanning message text.

  • Tier 3 — fetch. tool_get_attachment(attachment_id) returns the file. Image MIME types come back inline (HEIC is converted to PNG so it can be viewed directly). PDFs, video, and audio come back as a filesystem path the agent can read with its own tools. Inline image bytes are capped at 5MB by default to avoid context blowup; oversized images fall back to path return.

Stickers, link-preview "balloon" payloads, and .pluginPayloadAttachment containers are filtered out by default.

Recipient formats

For direct sends, E.164 phone numbers with a leading + are the most reliable format, such as +14155551234. Bare digit phone numbers with a country code are normalized before sending, and 10-digit US numbers are sent as +1.... tool_find_contact returns phone matches in the same send-ready format.

Integration

Claude Desktop Integration

Option 1: Claude Desktop Extension

This repo includes an MCPB-compatible manifest.json for Claude Desktop's one-click extension flow.

Copy & paste — that's it
yarn global add @anthropic-ai/mcpb
mcpb pack

Install the generated .mcpb file from Claude Desktop Settings > Extensions > Advanced settings > Install Extension....

Claude Desktop, or the terminal used to package/run the extension, still needs Full Disk Access to read Messages.

Building the extension

Build the .mcpb with the build script:

Copy & paste — that's it
python scripts/build_mcpb.py # build for the host architecture
python scripts/build_mcpb.py --arch x86_64 # build for Intel macs

By default it vendors a uv binary into the bundle (bin/uv) so the extension also runs on machines without uv installed — that binary is architecture specific (build one .mcpb per arch) and downloads Python and dependencies on first launch (network required once). Pass --no-bundle to pack against the system uv instead; see python scripts/build_mcpb.py --help for all options.

Option 2: Manual Config

  • Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json

  • Add the following configuration:

Copy & paste — that's it
{
 "mcpServers": {
 "messages": {
 "command": "uvx",
 "args": [
 "mac-messages-mcp"
 ]
 }
 }
}

Cursor Integration

Option 1: One-Click Install (Recommended)

Option 2: Manual Setup

Go to Cursor Settings > MCP and paste this as a command:

Copy & paste — that's it
uvx mac-messages-mcp

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

Docker Container Integration

If you need to connect to mac-messages-mcp from a Docker container, you'll need to use the mcp-proxy package to bridge the stdio-based server to HTTP.

This repository also includes a Dockerfile for catalog checks and container builds:

Copy & paste — that's it
docker build -t mac-messages-mcp .

Messages.app automation is macOS-only and will not work inside a Linux container. Container use is primarily for MCP catalog compatibility and read-only database experiments with mounted data.

Setup Instructions

  • Install mcp-proxy on your macOS host:
Copy & paste — that's it
npm install -g mcp-proxy
  • Start the proxy server:
Copy & paste — that's it
# Using the published version
npx mcp-proxy uvx mac-messages-mcp --port 8000 --host 0.0.0.0

# Or using local development (if you encounter issues)
npx mcp-proxy uv run python -m mac_messages_mcp.server --port 8000 --host 0.0.0.0

  • Connect from Docker: Your Docker container can now connect to:

  • URL: http://host.docker.internal:8000/mcp (on macOS/Windows)

  • URL: http://<host-ip>:8000/mcp (on Linux)

  • Docker Compose example:

Copy & paste — that's it
version: '3.8'
services:
 your-app:
 image: your-image
 environment:
 MCP_MESSAGES_URL: "http://host.docker.internal:8000/mcp"
 extra_hosts:
 - "host.docker.internal:host-gateway" # For Linux hosts
  • Running multiple MCP servers:
Copy & paste — that's it
# Terminal 1 - Messages MCP on port 8001
npx mcp-proxy uvx mac-messages-mcp --port 8001 --host 0.0.0.0

# Terminal 2 - Another MCP server on port 8002
npx mcp-proxy uvx another-mcp-server --port 8002 --host 0.0.0.0

Note: Binding to 0.0.0.0 exposes the service to all network interfaces. In production, consider using more restrictive host bindings and adding authentication.

Option 1: Install from PyPI

Copy & paste — that's it
uv pip install mac-messages-mcp

Option 2: Install from source

Copy & paste — that's it
# Clone the repository
git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

# Install dependencies
uv install -e .

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:

Copy & paste — that's it
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.

License

MIT

Contributing

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

Star History