Log inSubmit server
Mac Messages MCP logo

Mac Messages MCP

by carterlasalle

Reads and sends macOS Messages data through MCP, with contact, chat, attachment, and permission diagnostics.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Mac Messages MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "carterlasalle-mac-messages-mcp": {
      "command": "uvx",
      "args": [
        "mac-messages-mcp"
      ],
      "env": {
        "MAC_MESSAGES_REGION": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Automated check passed— started and listed 11 tools correctly (3d ago).

Overview

carterlasalle/mac_messages_mcp MCP server connects local macOS Messages and Contacts data to MCP clients. It reads message history, searches message text, resolves contacts, lists group chats, inspects attachments, and can send direct or group messages through Messages.app. Reach for it when an agent needs access to iMessage data on the same Mac. macOS permissions, Messages sign-in, and Full Disk Access are required for the relevant operations.

Use cases

  • Read recent Messages conversations
  • Search message history by approximate text
  • Find contacts and group chat identifiers
  • Inspect message attachments
  • Send direct or group messages from a Mac

Key features

  • Recent message retrieval with contact and group filters
  • Fuzzy message search across configurable history
  • Contact and group chat lookup
  • Attachment metadata search and retrieval
  • iMessage availability and database diagnostics
  • Direct and group message sending

Tools11

What Mac Messages MCP lets your agent do. Expand a tool for its parameters.

Verified live~2.7k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

8/8 checks healthy over the last 78d

What it can do

From the 11 tools this server returned when we ran it.

Runs commands · 7Can delete or modify data · 5Makes network requests · 1Read-only tools · 3
Network at startup2 connections
Files written at startup13

Observed 2026-10-24 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · mac-messages-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars336Stargazers on the source repository.
Last commit1d agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed11Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Mac Messages MCP works

What carterlasalle/mac_messages_mcp MCP server does

carterlasalle/mac_messages_mcp MCP server gives an MCP client access to the local Messages and Contacts data on macOS. It can retrieve recent messages, search message bodies using approximate text matching, find contacts by name, and list named group chats with their identifiers. Message searches normally cover the last 30 days, while hours=0 searches all available history.

The server also works with message attachments. It can search attachment metadata using dates, contacts, MIME types, and result limits, then fetch a selected attachment. Small images may be returned inline, HEIC images can be converted to PNG, and larger or non-image files may be returned as local paths.

Sending is an explicit operation through Messages.app rather than a database write. The server supports direct and group messages, with iMessage and eligible phone-recipient SMS/RCS fallback described by the project.

How it works

carterlasalle/mac_messages_mcp MCP server runs locally and opens the Messages and Contacts databases read-only. It returns only the data requested by the MCP client. Messages.app automation is used when the client calls the send tool, so read operations and sending have different permission requirements.

The available tools include tool_get_recent_messages, tool_fuzzy_search_messages, tool_find_contact, tool_get_chats, tool_search_attachments, and tool_get_attachment. Diagnostic tools check database access, Contacts access, contact availability, and likely iMessage reachability for a phone number or email. tool_send_message sends one direct or group message through Messages.app.

Phone numbers in national notation are normalized using a region selected at startup. The server uses the Mac's locale by default, with an optional MAC_MESSAGES_REGION override. Numbers already written in E.164 format do not need this setting.

Setup and configuration

Install uv with Homebrew, then run the server through uvx mac-messages-mcp. Python 3.10 or newer is required; uvx provisions an isolated environment and can install the package on first launch.

Configure the server as a stdio MCP server in the client of your choice. The README provides setup instructions for Claude Desktop, Claude Code, Codex clients, Cursor, and VS Code/GitHub Copilot. The common command is uvx mac-messages-mcp; clients that cannot locate uvx may need its absolute path.

Enable Full Disk Access for the application launching the server. Depending on the operation, macOS may also request Contacts access and permission for the launching application to control Messages. Messages.app must be open, signed in, and able to send a normal message before sending is used. After changing permissions or the region setting, restart the relevant application or server.

Limitations and notes

carterlasalle/mac_messages_mcp MCP server is macOS-only. Reading messages requires Full Disk Access, while sending additionally requires a Mac signed in to Messages and automation permission for the launching application.

The server accesses local databases and does not describe a remote or hosted deployment. Attachment results vary by file type and size: some images can be included in the response, while larger or unsupported files are represented by a local path. Contact and address-book diagnostics are available when troubleshooting permission or database access problems.

Sending should be treated as a side-effecting action. A client can first resolve a contact, inspect chat identifiers, and check likely iMessage availability before calling the send tool, but the material does not indicate that sending requires a separate confirmation step built into the server.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Mac Messages MCP

carterlasalle/mac_messages_mcp is an MCP server that connects macOS Messages and Contacts data to MCP clients. Its main tools read recent messages, search message text, find contacts, list chats, inspect attachments, check access, and send direct or group messages through Messages.app. It runs locally on macOS.

Install `uv`, then configure your MCP client to run `uvx mac-messages-mcp`. The server requires Python 3.10 or newer, although `uvx` provisions a compatible environment. Add the command using your client's stdio MCP configuration and restart the client after saving it.

Yes, carterlasalle/mac_messages_mcp works with Cursor through a stdio configuration. In Cursor Settings, open Tools & MCP, add a new MCP server, and use `uvx` with `mac-messages-mcp` as its argument. Restart the server from Cursor's MCP settings after saving.

It needs Full Disk Access for the application launching the server to read Messages data. macOS may separately request Contacts access and permission to control Messages. Sending also requires Messages.app to be open, signed in, and able to send normally.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMac Messages MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/carterlasalle-mac-messages-mcp?style=directory)](https://allmcps.com/mcp/carterlasalle-mac-messages-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/carterlasalle-mac-messages-mcp"><img src="https://allmcps.com/api/badge/carterlasalle-mac-messages-mcp?style=directory" alt="Mac Messages MCP on AllMCPs" /></a>