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.

[!IMPORTANT] This server is macOS-only. Reading messages requires Full Disk Access. Sending requires a Mac signed into Messages plus permission for the launching app to automate Messages.

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"]
    }
  }
}

[!NOTE] VS Code uses a top-level servers object. Claude Desktop and Cursor use mcpServers.

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