What is mac-messages?

A macOS Messages connection that lets an agent read, search, and manage messages and contacts through the local Messages and Contacts databases. Sending messages or changing contacts requires macOS permissions and the relevant apps to be available.

It is for finding messages and attachments, listing chats, resolving contacts, creating contacts, scheduling messages, and sending messages through Messages.app.

It avoids switching between conversations, contact records, and attachments when looking up or sending information.

How carterlasalle/mac_messages_mcp configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to carterlasalle/mac_messages_mcp. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/carterlasalle/mac_messages_mcp/main/.claude/skills/mac-messages/SKILL.md

Clone the repo

git clone --depth 1 https://github.com/carterlasalle/mac_messages_mcp

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/carterlasalle/mac_messages_mcp/mac-messages/github.svg)](https://agentmods.dev/skills/carterlasalle/mac_messages_mcp/mac-messages)

Your own site

<a href="https://agentmods.dev/skills/carterlasalle/mac_messages_mcp/mac-messages"><img src="https://agentmods.dev/badge/skills/carterlasalle/mac_messages_mcp/mac-messages/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/carterlasalle/mac_messages_mcp/mac-messages"><img src="https://agentmods.dev/badge/skills/carterlasalle/mac_messages_mcp/mac-messages.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 90 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 3,076 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00090	$0.03076
Opus 5.5	$0.00036	$0.01230
Sonnet 5.5	$0.00018	$0.00615
Haiku 4.5	$0.00009	$0.00308

Measured 1mo ago against content hash 82154ba09469, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

mac-messages scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.claude/skills/mac-messages/SKILL.md · 241 lines

How it starts

The opening of the file, as written. The whole thing — 241 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Mac Messages MCP

Call the mac-messages MCP server to read and search the local Messages database, list conversations, resolve Contacts entries, fetch or search attachments, create a contact, schedule a message, and send one outgoing message through Messages.app.

Preconditions

The server runs on macOS only and reads ~/Library/Messages/chat.db plus the Contacts/AddressBook databases.

The host app or terminal needs Full Disk Access.
Sending needs Automation permission for Messages.app, a signed-in Messages account, and Messages.app able to reach the recipient.
Creating a contact needs Automation permission for Contacts.app.
Permission failures surface as tool text such as Operation not permitted or unable to open database file; they are not exceptions you can retry past.

On the first message-related task in a session, confirm the server can read its data before assuming a lookup result of "no messages" is real:

tool_check_db_access — Messages database.
tool_check_addressbook — Contacts database.

Tool map

Goal	Tool
Recent messages, filtered by contact, chat, date range, or unread	`tool_get_recent_messages`
Message text matching a phrase, scoped to a contact or chat	`tool_fuzzy_search_messages`
Every conversation with kind, counts, and last activity	`tool_list_conversations`
Block until a newer message arrives	`tool_wait_for_new_messages`
Contact name to send-ready number(s)	`tool_find_contact`
Send-ready group chat names and IDs	`tool_get_chats`
Attachment metadata by date, contact, or MIME type	`tool_search_attachments`
Text inside attachment contents	`tool_search_attachment_contents`
One attachment by ID	`tool_get_attachment`
Whether a recipient is reachable over iMessage	`tool_check_imessage_availability`
Diagnostics: Messages DB, AddressBook, contact count	`tool_check_db_access`, `tool_check_addressbook`, `tool_check_contacts`
Send one message now	`tool_send_message`
Queue a message for later	`tool_schedule_message`, `tool_list_scheduled_messages`, `tool_cancel_scheduled_message`
Create one Contacts entry	`tool_create_contact`

Read the full file on GitHub · 241 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago First seen · 241 lines · 90 tokens per session scan A 82154ba09469

Subscribe to this mod's changes

mac-messages is a skill published in the GitHub repository carterlasalle/mac_messages_mcp (343 stars, last pushed yesterday), licensed MIT. It adds 90 tokens to every session and 3,076 once invoked, about $0.0004 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-10-07.

Productivity applescript claude contacts cursor imessage mac

mac-messages next to 6 skills from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
mac-messagescarterlasalle/mac_messages_mcp	Skill	343	yesterday	MIT	A	90	Claude Code
imessage-inboxbenelser/imessage-tools	Skill	3	14d ago	MIT	A	9	Claude Code
peon-ping-togglePeonPing/peon-ping	Skill	5.1k	18d ago	MIT	A	58	Claude Code
peon-ping-logPeonPing/peon-ping	Skill	5.1k	18d ago	MIT	A	64	Claude Code
planning-with-filesmxyhi/ok-skills	Skill	509	yesterday	Apache-2.0	A	117	Claude Code
getting-starteddavekilleen/Dex	Skill	512	8d ago	MIT	A	70	Claude Code, Codex
resume-builderdavekilleen/Dex	Skill	512	8d ago	MIT	A	12	Claude Code, Codex

mac_messages_mcp: Skill for Claude Code