Skip to content
Back to search

mac_messages_mcp

An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to query and analyze iMessage conversations. It includes robust phone number validation, attachment processing, contact management, group chat handling, and full support for sending and receiving messages.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/carterlasalle/mac_messages_mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/carterlasalle/mac_messages_mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/carterlasalle--mac-messages-mcp/badge.svg)](/listings/carterlasalle--mac-messages-mcp)

HTML

<a href="/listings/carterlasalle--mac-messages-mcp"><img src="/api/listings/carterlasalle--mac-messages-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](#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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 689 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # Mac Messages MCP
  3. **Read, search, and send macOS Messages from any local MCP client.**
  4. [![PyPI](https://img.shields.io/pypi/v/mac-messages-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/mac-messages-mcp/)
  5. [![Python](https://img.shields.io/pypi/pyversions/mac-messages-mcp?logo=python&logoColor=white)](https://pypi.org/project/mac-messages-mcp/)
  6. [![CI](https://github.com/carterlasalle/mac_messages_mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/carterlasalle/mac_messages_mcp/actions/workflows/ci.yml)
  7. [![Downloads](https://static.pepy.tech/badge/mac-messages-mcp)](https://pepy.tech/project/mac-messages-mcp)
  8. [![macOS](https://img.shields.io/badge/macOS-only-000000?logo=apple&logoColor=white)](#quick-start)
  9. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  10. [Quick start](#quick-start) · [Available tools](#available-tools) · [Agent skill](#agent-skill) · [Command-line interface](#command-line-interface) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)
  11. </div>
  12. Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and
  13. send messages through the macOS Messages app.
  14. Mac Messages MCP runs locally on your Mac. It opens the Messages and Contacts
  15. databases read-only, returns only the data a client asks for, and uses
  16. Messages.app automation only when the client explicitly calls the send tool.
  17. > [!IMPORTANT] This server is macOS-only. Reading messages requires Full Disk
  18. > Access. Sending requires a Mac signed into Messages plus permission for the
  19. > launching app to automate Messages.
  20. ## How it works
  21. ```mermaid
  22. flowchart LR
  23. A[MCP client] -->|stdio| B[mac-messages-mcp]
  24. B --> C{Tool call}
  25. C -->|read tools| D[(chat.db read-only)]
  26. C -->|read tools| E[(AddressBook read-only)]
  27. C -->|send tools| F[Messages.app]
  28. F --> G[Recipient]
  29. D --> H[Untrusted-output boundary]
  30. E --> H
  31. H --> A
  32. ```
  33. Everything the client reads comes from the local SQLite databases, opened
  34. read-only. Everything that leaves the machine goes out through Messages.app,
  35. under an explicit send tool call. Message- and contact-derived text is fenced as
  36. untrusted data on the way back to the model.
  37. ## Capabilities
  38. | Area | What Mac Messages MCP provides |
  39. |---|---|
  40. | Reading | Recent messages across all conversations or filtered by contact, group chat, date range, or unread state; paging with `limit`/`offset` and forward-cursor reads |
  41. | Conversations | Every conversation (1:1, business, and group) with kind, message and unread counts, last activity, and a blocking wait for new messages |
  42. | Search | Fuzzy message-body search across a time window or all history, scoped to a contact or conversation |
  43. | Context | Per-message service (iMessage/SMS/RCS), unread and delivery state, tapbacks, and threaded replies |
  44. | Contacts | Fuzzy contact lookup by approximate name, send-ready phone numbers, and contact creation |
  45. | Group chats | Named group chat discovery with stable chat IDs reused for reads and sends |
  46. | Sending | iMessage with SMS/RCS fallback, file attachments, optional human approval through MCP elicitation, and iMessage reachability checks |
  47. | Scheduling | Queue a message for later delivery while the server process stays alive |
  48. | Attachments | Metadata search, best-effort text/PDF content search, inline images (HEIC converted to PNG), and local paths for larger or non-image files |
  49. | Diagnostics | Messages and Contacts database permission checks from inside the MCP client |
  50. | Privacy | Read-only SQLite access, no message archive of its own, and a structural untrusted-output boundary |
  51. ## Quick start
  52. ### 1. Install `uv`
  53. ```bash
  54. brew install uv
  55. ```
  56. Confirm that the launcher is available:
  57. ```bash
  58. uvx --version
  59. ```
  60. Python 3.10 or newer is required. `uvx` can provision a compatible Python and
  61. installs Mac Messages MCP in an isolated environment, so you do not need to
  62. create a virtual environment first.
  63. ### 2. Grant macOS permissions
  64. Open **System Settings → Privacy & Security → Full Disk Access** and enable the
  65. app that will launch the MCP server:
  66. - Claude Desktop, Cursor, VS Code, or the ChatGPT desktop app when configured in
  67. that app
  68. - Terminal, iTerm2, Ghostty, or another terminal when using Claude Code or Codex
  69. CLI from that terminal
  70. Quit and reopen the app after changing Full Disk Access. On the first contact
  71. lookup or send, macOS may separately ask for access to Contacts or permission to
  72. control Messages. Allow those prompts.
  73. Also make sure Messages.app is open, signed in, and already able to send a
  74. normal message.
  75. ### 3. Add the server to your MCP client
  76. The server command is the same everywhere:
  77. ```text
  78. uvx mac-messages-mcp
  79. ```
  80. Choose your client below.
  81. #### Claude Desktop
  82. Open **Claude → Settings → Developer → Edit Config**, then add:
  83. ```json
  84. {
  85. "mcpServers": {
  86. "mac-messages": {
  87. "command": "uvx",
  88. "args": ["mac-messages-mcp"]
  89. }
  90. }
  91. }
  92. ```
  93. Preserve any other servers already in `claude_desktop_config.json`, save the
  94. file, and restart Claude Desktop.
  95. Claude Desktop also supports installable `.mcpb` extensions. See
  96. [Build the Claude Desktop extension](#build-the-claude-desktop-extension) if you
  97. want to package this repository as one.
  98. #### Claude Code
  99. Add it once at user scope so it is available in every project:
  100. ```bash
  101. claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcp
  102. ```
  103. Verify it:
  104. ```bash
  105. claude mcp get mac-messages
  106. ```
  107. Inside Claude Code, run `/mcp` to inspect the connection and tools.
  108. #### Codex CLI, Codex IDE extension, and ChatGPT desktop app
  109. Codex clients on the same Mac share MCP configuration. Add the server with:
  110. ```bash
  111. codex mcp add mac-messages -- uvx mac-messages-mcp
  112. ```
  113. Then verify it:
  114. ```bash
  115. codex mcp list
  116. ```
  117. You can also add it directly to `~/.codex/config.toml`:
  118. ```toml
  119. [mcp_servers.mac-messages]
  120. command = "uvx"
  121. args = ["mac-messages-mcp"]
  122. ```
  123. Restart the desktop app or IDE extension after changing the configuration. In
  124. Codex CLI, use `/mcp` to view the active server.
  125. #### Cursor
  126. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=mac-messages-mcp&config=eyJjb21tYW5kIjoidXZ4IG1hYy1tZXNzYWdlcy1tY3AifQ%3D%3D)
  127. Or open **Cursor Settings → Tools & MCP → New MCP Server** and use:
  128. ```json
  129. {
  130. "mcpServers": {
  131. "mac-messages": {
  132. "command": "uvx",
  133. "args": ["mac-messages-mcp"]
  134. }
  135. }
  136. }
  137. ```
  138. Restart the server from Cursor's MCP settings after saving.
  139. #### VS Code / GitHub Copilot
  140. Open the Command Palette and run **MCP: Add Server**. Choose **Command
  141. (stdio)**, enter `uvx` as the command, add `mac-messages-mcp` as the argument,
  142. and install it globally.
  143. Or add it from a terminal:
  144. ```bash
  145. code --add-mcp '{"name":"mac-messages","command":"uvx","args":["mac-messages-mcp"]}'
  146. ```
  147. The equivalent user or workspace `mcp.json` entry is:
  148. ```json
  149. {
  150. "servers": {
  151. "mac-messages": {
  152. "type": "stdio",
  153. "command": "uvx",
  154. "args": ["mac-messages-mcp"]
  155. }
  156. }
  157. }
  158. ```
  159. > [!NOTE] VS Code uses a top-level `servers` object. Claude Desktop and Cursor
  160. > use `mcpServers`.
  161. #### Other stdio MCP clients
  162. Use this generic server definition:
  163. ```json
  164. {
  165. "command": "uvx",
  166. "args": ["mac-messages-mcp"]
  167. }
  168. ```
  169. If a GUI client reports that `uvx` cannot be found, run `which uvx` in Terminal
  170. and replace `"uvx"` with the returned absolute path. Homebrew commonly installs
  171. it at `/opt/homebrew/bin/uvx` on Apple silicon and `/usr/local/bin/uvx` on Intel
  172. Macs.
  173. ### 4. Verify the connection
  174. Ask your client to call `tool_check_db_access`, then `tool_check_addressbook`.
  175. Once both succeed, try prompts such as:
  176. ```text
  177. Show me my messages from the last two hours.
  178. ```
  179. ```text
  180. Find messages from Carter about dinner in the last 30 days.
  181. ```
  182. ```text
  183. Find PDFs sent to me this month, but do not open any yet.
  184. ```
  185. ```text
  186. Find Jordan in my contacts and draft a message saying I am running 10 minutes
  187. late. Do not send it until I confirm.
  188. ```
  189. The first `uvx` launch can take longer while it downloads and caches Python
  190. dependencies.
  191. ### 5. Optional: set the phone number region
  192. Phone numbers written in national format (`06 39 98 00 01`, `(415) 555-1234`)
  193. have to be expanded to E.164 before they can be matched against the Messages
  194. database, and that expansion needs to know which country they belong to. The
  195. server reads your Mac's own region setting for this, so on a correctly
  196. configured Mac there is nothing to do.
  197. Set `MAC_MESSAGES_REGION` to an [ISO 3166-1 alpha-2][iso3166] code when your
  198. numbers belong to a different region than your Mac is configured for — a French
  199. SIM on a Mac set to `en_US`, say:
  200. ```json
  201. {
  202. "mcpServers": {
  203. "mac-messages": {
  204. "command": "uvx",
  205. "args": ["mac-messages-mcp"],
  206. "env": { "MAC_MESSAGES_REGION": "FR" }
  207. }
  208. }
  209. }
  210. ```
  211. For Claude Code:
  212. ```bash
  213. claude mcp add --transport stdio --scope user \
  214. --env MAC_MESSAGES_REGION=FR \
  215. mac-messages -- uvx mac-messages-mcp
  216. ```
  217. The region is resolved once at startup, so restart the server after changing
  218. it. Resolution order: `MAC_MESSAGES_REGION`, then the macOS `AppleLocale`
  219. preference, then `LC_ALL` / `LC_CTYPE` / `LANG`, then `US`. Numbers already
  220. written in E.164 (`+33639980001`) are never reinterpreted and need none of
  221. this.
  222. [iso3166]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
  223. ## Available tools
  224. <!-- markdownlint-disable MD013 -->
  225. | Tool | Purpose | Side effect |
  226. | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
  227. | `tool_get_recent_messages` | Read recent messages, filtered by contact, group chat ID, date range, or unread state; page with `limit`/`offset` | Read-only |
  228. | `tool_fuzzy_search_messages` | Search message bodies by approximate text match, scoped to a contact or chat; defaults to 30 days, or `hours=0` | Read-only |
  229. | `tool_list_conversations` | List every conversation with kind, message count, unread count, and last activity | Read-only |
  230. | `tool_wait_for_new_messages` | Block until a message newer than a ROWID cursor arrives, or the timeout expires | Read-only |
  231. | `tool_find_contact` | Fuzzy-match a name in Contacts and return phone numbers | Read-only |
  232. | `tool_get_chats` | List named group chats and their identifiers | Read-only |
  233. | `tool_search_attachments` | Find attachment metadata by date, contact, MIME type, and limit | Read-only |
  234. | `tool_search_attachment_contents` | Search inside attachment text/PDF contents by date, contact, and MIME type | Read-only |
  235. | `tool_get_attachment` | Fetch one attachment by ID, inline when supported or as a local path | Read-only |
  236. | `tool_check_imessage_availability` | Check likely iMessage availability for a phone number or email | Read-only |
  237. | `tool_check_db_access` | Diagnose access to `~/Library/Messages/chat.db` | Read-only |
  238. | `tool_check_contacts` | Return a contact count and a small sample | Read-only |
  239. | `tool_check_addressbook` | Diagnose Contacts/AddressBook database access | Read-only |
  240. | `tool_send_message` | Send one direct or group message through Messages.app, optionally with file attachments and elicitation approval | **Sends a real message** |
  241. | `tool_create_contact` | Create one Contacts.app entry with a phone number | **Changes Contacts** |
  242. | `tool_schedule_message` | Queue a message for later delivery while this server process runs | **Sends a real message later** |
  243. | `tool_list_scheduled_messages` | List the in-process scheduled-message queue and its status | Read-only |
  244. | `tool_cancel_scheduled_message` | Cancel one pending scheduled message | Read-only |
  245. <!-- markdownlint-enable MD013 -->
  246. Three MCP prompts ship with the server: `triage_unread_messages`,
  247. `summarize_recent_messages`, and `draft_reply`. They are starting points that
  248. tell the agent which read tools to call, and they never send anything.
  249. The server also exposes two MCP resources:
  250. - `messages://recent/{hours}`
  251. - `messages://contact/{contact}/{hours}`
  252. ### Message metadata, paging, and cursors
  253. Reads append compact tags when the message row carries the data, so output stays
  254. unchanged for old or partial databases:
  255. ```text
  256. [2026-10-01 09:14:02] Alice [iMessage] [unread]: running late, sorry
  257. [2026-10-01 09:15:40] You [iMessage] [not delivered]: no worries
  258. [2026-10-01 09:15:55] Alice [iMessage] [tapback: liked]: (reaction)
  259. [2026-10-01 09:16:10] Bob [SMS] [reply]: got it
  260. ```
  261. `tool_get_recent_messages` closes with a note when a page fills up, naming the
  262. next `offset` to use. Passing `since_rowid` switches it to a forward cursor read
  263. (oldest first) that ignores the `hours` window, which is the pattern
  264. `tool_wait_for_new_messages` polls on.
  265. ### What it deliberately does not do
  266. Messages.app automation does not expose these, so the server refuses rather than
  267. pretending:
  268. - sending tapbacks, message effects, or a subject line (only text and file
  269. attachments can be sent)
  270. - creating a group chat, adding or removing participants, or attaching files to
  271. a group chat
  272. - editing, unsending, deleting, or marking a message read, and saving drafts
  273. - editing or merging an existing Contacts card (`tool_create_contact` creates a
  274. new one)
  275. - scheduled sends rely on the server process staying alive; nothing is
  276. persisted, so a scheduled message is lost if the client disconnects first
  277. ## Agent skill
  278. The repository ships an [agent skill](.claude/skills/mac-messages/SKILL.md)
  279. that tells an agent when and how to call each tool: checking access first,
  280. listing conversations, resolving a recipient or group chat, searching message
  281. text or attachment contents, paging attachments, confirming a send, scheduling
  282. a later send, and treating message-derived output as untrusted data. Claude Code
  283. discovers it automatically when you work in this repository.
  284. To use it from another project, copy the skill directory into that project's
  285. `.claude/skills/`, or into `~/.claude/skills/` to make it available everywhere:
  286. ```bash
  287. mkdir -p ~/.claude/skills
  288. cp -R .claude/skills/mac-messages ~/.claude/skills/
  289. ```
  290. ## Working with contacts, chats, and attachments
  291. ### Recipients
  292. For direct messages, E.164 phone numbers are the most reliable format:
  293. ```text
  294. +14155551234
  295. ```
  296. Numbers written in national format work too. They are expanded to E.164 using
  297. the region your Mac is configured for, so `(415) 555-1234` becomes
  298. `+14155551234` on a US Mac and `06 39 98 00 01` becomes `+33639980001` on a
  299. French one. Set `MAC_MESSAGES_REGION` to an ISO 3166-1 alpha-2 code
  300. (`MAC_MESSAGES_REGION=GB`) when your numbers belong to a different region than
  301. your Mac does. Numbers already in E.164 are never reinterpreted.
  302. The server also accepts email addresses, contact names, and `contact:N`
  303. selections returned after an ambiguous contact search.
  304. For a group conversation, call `tool_get_chats`, pass its chat ID to
  305. `tool_send_message`, and set `group_chat=true`. Use the same ID as `chat_id` in
  306. `tool_get_recent_messages` to read that conversation.
  307. ### Attachments
  308. Attachment access is deliberately split into three steps:
  309. 1. Message reads and searches add compact markers such as
  310. `[attachments: #42 image/jpeg (invitation.jpg)]`.
  311. 2. `tool_search_attachments` searches metadata without loading file contents.
  312. 3. `tool_get_attachment` fetches one selected attachment.
  313. Images up to 5 MB are returned inline by default. HEIC images are converted to
  314. PNG. Larger images, PDFs, video, and audio are returned as local filesystem
  315. paths so the MCP client can decide whether to open them. Stickers, link-preview
  316. payloads, and `.pluginPayloadAttachment` containers are filtered out.
  317. ## Architecture
  318. Mac Messages MCP is a small Python package with one job per module:
  319. ```text
  320. mac_messages_mcp/
  321. server.py FastMCP server: tools, prompts, resources, stdio transport
  322. cli.py mac-messages-cli terminal interface
  323. messages.py chat.db reads and AppleScript sends for Messages.app
  324. content.py Best-effort text/PDF attachment content search
  325. phone.py E.164 normalization against the Mac's configured region
  326. scheduler.py In-process scheduled-send queue
  327. untrusted.py Structural neutralization of Messages/Contacts-derived text
  328. scripts/
  329. build_mcpb.py Builds the Claude Desktop .mcpb extension
  330. bump_version.py Keeps version metadata in sync across release files
  331. tests/ Pytest suite over temporary databases and mocked AppleScript
  332. main.py Stdio entry point for MCP clients
  333. manifest.json MCPB manifest for the Claude Desktop extension
  334. ```
  335. Reads go straight to `chat.db` and the AddressBook database; sends go through
  336. AppleScript into Messages.app. Model-facing payloads pass through
  337. `untrusted.py` before they reach the client.
  338. ## Privacy and security
  339. - Messages and Contacts SQLite connections use read-only mode and SQLite
  340. `query_only`.
  341. - The server does not upload, mirror, index, or maintain its own message
  342. archive.
  343. - Results are written to the local MCP stdio connection started by your client.
  344. - Messages/Contacts-derived tool and resource output is structurally
  345. neutralized (embedded newlines and ASCII controls cannot form extra
  346. transcript lines; invisible, format, and bidi characters are shown as
  347. escapes) and returned inside an explicit `<untrusted-mcp-output>` block.
  348. That is not an anti-injection guarantee: third-party iMessage/SMS content
  349. can still attempt prompt injection. The server makes that content
  350. non-structural and labeled; the client must not treat it as authorization,
  351. confirmation, or tool instructions.
  352. - Attachment bytes are returned only after an explicit fetch and are
  353. size-limited for inline images. Filename, MIME, path, and other metadata
  354. text is neutralized with the same boundary; image payloads are preserved.
  355. - Sending is isolated in `tool_send_message`, escapes AppleScript inputs, and
  356. uses a bounded execution timeout. This server does not perform human
  357. confirmation; the MCP client must gate sends.
  358. - Full Disk Access is broader than Messages access. Grant it only to MCP clients
  359. you trust and review the destination before approving a send.
  360. See [SECURITY.md](SECURITY.md) to report a vulnerability privately.
  361. ## Troubleshooting
  362. ### `uvx` or `spawn uvx ENOENT`
  363. The GUI app cannot see your shell's Homebrew path. Run:
  364. ```bash
  365. which uvx
  366. ```
  367. Use that full path as the MCP `command`, then restart the client.
  368. ### `Operation not permitted`, `unable to open database file`, or no messages
  369. Grant Full Disk Access to the app that launches the server, not just to
  370. Messages.app. Completely quit and reopen the launcher afterward, then call
  371. `tool_check_db_access` again.
  372. For Claude Code or Codex CLI, the launcher is normally your terminal. For a
  373. desktop or IDE integration, it is normally Claude Desktop, Cursor, VS Code, or
  374. the ChatGPT desktop app itself.
  375. ### Contacts are empty or contact lookup fails
  376. Allow the launching app to access Contacts if macOS prompts. Confirm Full Disk
  377. Access, restart the app, and call `tool_check_addressbook` followed by
  378. `tool_check_contacts`.
  379. If contacts are listed but their numbers carry the wrong country code, the
  380. server is expanding your national-format numbers against the wrong region. Set
  381. `MAC_MESSAGES_REGION` to the right ISO 3166-1 alpha-2 code and restart the
  382. server.
  383. ### Reading works but sending fails
  384. 1. Open Messages.app and send a message manually to confirm the account and
  385. recipient work.
  386. 2. Check **System Settings → Privacy & Security → Automation** and allow the
  387. launching app to control Messages.
  388. 3. Prefer an E.164 number such as `+14155551234` for a direct recipient.
  389. 4. Use `tool_check_imessage_availability` to inspect the likely route.
  390. ### An attachment is listed but cannot be opened
  391. Messages may retain database metadata after macOS has offloaded the file. Open
  392. the conversation in Messages.app and download the attachment, then retry
  393. `tool_get_attachment`.
  394. ### The server appears to hang when run in Terminal
  395. That is normal for an MCP stdio server: it waits for protocol input from a
  396. client. Use your client's MCP status view, or launch the MCP Inspector:
  397. ```bash
  398. yarn dlx @modelcontextprotocol/inspector uvx mac-messages-mcp
  399. ```
  400. ## Install as a standalone tool
  401. MCP clients can launch the package directly with `uvx`; a permanent installation
  402. is optional.
  403. ```bash
  404. uv tool install mac-messages-mcp
  405. mac-messages-mcp
  406. ```
  407. Upgrade or remove it with:
  408. ```bash
  409. uv tool upgrade mac-messages-mcp
  410. uv tool uninstall mac-messages-mcp
  411. ```
  412. ## Python API
  413. The MCP server is the primary interface, but the package also exports its core
  414. read/send functions:
  415. ```python
  416. from mac_messages_mcp import get_recent_messages, send_message
  417. recent = get_recent_messages(hours=48)
  418. print(recent)
  419. result = send_message(
  420. recipient="+14155551234",
  421. message="Hello from Mac Messages MCP!",
  422. )
  423. print(result)
  424. ```
  425. These calls use the same macOS permissions and can send real messages.
  426. ## Command-line interface
  427. The package also installs a `mac-messages-cli` command, so Messages can be read,
  428. searched, and sent from a terminal without an MCP client. It uses the same local
  429. databases and needs the same macOS permissions as the server; granting Full Disk
  430. Access to your terminal covers both.
  431. ```bash
  432. uv tool install mac-messages-mcp
  433. mac-messages-cli --help
  434. ```
  435. | Command | Purpose |
  436. | ------------------- | ------------------------------------------------------------------ |
  437. | `recent` | Recent messages, optionally filtered by contact or group chat ID. |
  438. | `search TERM` | Fuzzy-search message text within a time window. |
  439. | `contact NAME` | Fuzzy-match a name in Contacts and print send-ready numbers. |
  440. | `contacts` | Contact count plus a sample of AddressBook entries. |
  441. | `chats` | Named group chats and their identifiers. |
  442. | `attachments` | Attachment metadata by date range, contact, and MIME type. |
  443. | `attachment ID` | One attachment's metadata and local path, with optional `--save`. |
  444. | `send` | Send one message through Messages.app. |
  445. | `check` | Diagnose Messages/AddressBook access and iMessage reachability. |
  446. ```bash
  447. # Last 48 hours, or one contact, or one group chat
  448. mac-messages-cli recent -n 48
  449. mac-messages-cli recent --contact "Jordan"
  450. mac-messages-cli recent --chat chat721054478304420871
  451. # Fuzzy search: last 30 days by default, or all history with -n 0
  452. mac-messages-cli search "dinner" -t 0.7
  453. mac-messages-cli search "dinner" -n 0
  454. # Contacts and group chats
  455. mac-messages-cli contact "Jordan"
  456. mac-messages-cli chats
  457. # Attachments: search metadata, then fetch or save one file
  458. mac-messages-cli attachments --since 2026-09-01 --mime image/ --limit 20
  459. mac-messages-cli attachment 42 --save ~/Desktop/invitation.jpg
  460. # Permissions and iMessage reachability
  461. mac-messages-cli check --recipient +14155551234
  462. # Sending prompts for confirmation unless --yes is passed
  463. mac-messages-cli send +14155551234 "Running 10 minutes late."
  464. ```
  465. `mac-messages-cli send` asks for `y/N` confirmation before sending. When stdin is
  466. not a terminal it refuses to send unless `--yes` is passed, so an unattended
  467. script cannot send a message by accident. Commands exit non-zero when a lookup
  468. fails, so the output is safe to branch on in scripts.
  469. ## Development
  470. ```bash
  471. git clone https://github.com/carterlasalle/mac_messages_mcp.git
  472. cd mac_messages_mcp
  473. uv sync --frozen --extra dev
  474. uv run pytest
  475. uv run black --check .
  476. uv run isort --check-only .
  477. uv build
  478. ```
  479. Tests mock AppleScript and use temporary database fixtures; they must never read
  480. a contributor's real Messages or Contacts data. See
  481. [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution checklist and
  482. [VERSIONING.md](VERSIONING.md) for releases.
  483. ### Build the Claude Desktop extension
  484. The repository includes an MCPB `manifest.json` and a build script that can
  485. bundle an architecture-specific `uv` binary:
  486. ```bash
  487. yarn global add @anthropic-ai/mcpb
  488. uv run python scripts/build_mcpb.py
  489. ```
  490. For an Intel build:
  491. ```bash
  492. uv run python scripts/build_mcpb.py --arch x86_64
  493. ```
  494. Install the generated `.mcpb` from **Claude Desktop → Settings → Extensions →
  495. Advanced settings → Install Extension…**. A bundled extension still needs
  496. network access on first launch to download Python and the package dependencies.
  497. Use `--no-bundle` to package against the system `uv`, or run
  498. `uv run python scripts/build_mcpb.py --help` for every option.
  499. ## Docker
  500. The included Dockerfile is for package and catalog validation. A Linux container
  501. cannot access macOS TCC permissions or automate Messages.app, so Docker is not a
  502. supported way to read or send messages on the host Mac.
  503. ## Documentation
  504. | Document | Purpose |
  505. |---|---|
  506. | [Agent skill](.claude/skills/mac-messages/SKILL.md) | When and how an agent should call each tool |
  507. | [Contributing](CONTRIBUTING.md) | Development workflow, checks, and pull-request standards |
  508. | [Security](SECURITY.md) | Private vulnerability reporting and the trust model |
  509. | [Versioning](VERSIONING.md) | Release and version metadata process |
  510. | [Changelog](CHANGELOG.md) | User-facing changes by release |
  511. ## Contributing
  512. Issues and focused pull requests are welcome. Do not include real message
  513. contents, contacts, phone numbers, database files, or attachments in bug reports
  514. or fixtures.
  515. ## License
  516. [MIT](LICENSE) © Carter Lasalle

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.