MCP SERVERSearch your own iMessage history by fuzzy text, pull a photo or PDF out of a thread by MIME type, and send one reply through the Messages app on the Mac the server runs on.
LABSCO SUMMARY
Ten of the eleven tools only read the local databases; sending is the one with an effect outside the machine, which makes the risk easy to reason about before you grant anything. The permissions are granular rather than one switch, which is why Messages database access and Contacts access each have their own diagnostic tool.
A read-mostly bridge to the local macOS Messages and AddressBook databases, opened read-only, with a single tool that sends — and that one drives Messages.app only when the client calls it.
macOS only, with Messages open, signed in and already able to send an ordinary message, plus uv and Python 3.10 or newer. The permissions are the actual install work: grant Full Disk Access to whatever launches the server — your MCP client, or the terminal you start it from — and quit and reopen that app afterwards. macOS then asks separately for Contacts access on the first name lookup and for permission to control Messages on the first send.
One command — uvx mac-messages-mcp
USE CASES
Fuzzy-search the text over a window rather than scrolling, and get the matches back with their scores.
Search attachments by date, sender and type, then fetch the one you want by id.
Resolve the name to a number, check they are reachable, and send the one message.
List the named chats, then read the recent messages for the one you have been ignoring.
Run the access checks — they name the permission or path that is missing instead of failing vaguely, and confirm contacts actually come back.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
tool_check_addressbookDiagnose read access to the local macOS AddressBook database.
This is read-only: it checks whether the server can locate and read local Contacts/AddressBook data and returns a plain-text diagnostic report with permission or path errors. It does not modify contacts. Use this when contact lookup fails; use tool_check_db_access when Messages database reads fail.
tool_check_contactsList a small sample of contacts available from AddressBook.
This is read-only: it loads cached local contact names and phone numbers and returns a plain-text count plus sample entries. Requires Contacts/AddressBook permission. Use this to confirm contact lookup is populated; use tool_find_contact to resolve a specific person, and tool_check_addressbook to diagnose permission or database access failures.
tool_check_db_accessDiagnose read access to the local macOS Messages database.
This is read-only: it checks whether the server can locate and query the Messages SQLite database and returns a plain-text diagnostic report with any permission or path errors. It requires Full Disk Access for the host app or terminal. Use this after message reads/searches fail or return permission errors; use tool_check_addressbook for Contacts/AddressBook access issues.
tool_check_imessage_availabilityCheck whether a recipient appears reachable through iMessage.
This is a read-only availability check against local Messages services; it does not send a message. Requires Messages to be configured on this Mac. Returns a plain-text result indicating iMessage availability or likely SMS/RCS fallback for phone numbers. Use this before tool_send_message when delivery route matters; use tool_find_contact first if you only have a contact name.
tool_find_contactFind AddressBook contacts by fuzzy name matching.
This is read-only: it searches local contacts and does not message anyone or change contacts. Requires Contacts/AddressBook permission for the host app or terminal. Returns a plain-text single match or a numbered list with confidence scores; use a returned "contact:N" selector with tool_send_message or tool_get_recent_messages. Use tool_check_contacts to inspect available cached contacts, and tool_fuzzy_search_messages when searching message text instead.
tool_fuzzy_search_messagesFuzzy-search local message text within a time window.
This is read-only: it queries the local Messages database and does not send, edit, or delete messages. Requires Full Disk Access for the host app or terminal. Returns a plain-text list of matching messages with similarity scores, timestamps, participants, sanitized bodies, and attachment markers when present. Use this for approximate text search; use tool_get_recent_messages for unfiltered chronological context and tool_find_contact for contact lookup.
tool_get_attachmentFetch a specific attachment by its database ROWID.
This is read-only: it resolves a local Messages attachment file and does not modify or delete it. Requires Full Disk Access for the host app or terminal. For image MIME types under max_bytes, returns the image inline so you can see it directly. For PDFs, video, audio, missing files, or oversize images, returns a plain-text filesystem path or error. Use tool_search_attachments first unless you already have an attachment ID.
tool_get_chatsList named group chats from the macOS Messages database.
This is read-only: it queries chat identifiers and display names and does not send, edit, or delete messages. Requires Full Disk Access for the host app or terminal. Returns a plain-text numbered list of group names and IDs. Use this before tool_send_message with group_chat=true; use tool_get_recent_messages when you need message contents instead of chat IDs.
tool_get_recent_messagesRead recent macOS Messages as a plain-text summary.
This is read-only: it queries the local Messages database and does not send, edit, or delete messages. Requires macOS Full Disk Access for the host app or terminal. Returns sanitized message text, timestamps, participants, and compact attachment markers when files are present. Use contact for one-to-one conversations or chat_id for a group conversation, but not both. Use this when you need chronological recent context; use tool_fuzzy_search_messages when searching for specific text, and tool_get_chats when you only need group chat IDs.
tool_search_attachmentsSearch message attachments by date range, contact, and MIME type.
This is read-only and returns metadata only; it does not return file bytes or modify attachments. Requires Full Disk Access for the host app or terminal. Results include attachment IDs, MIME types, filenames, sizes, timestamps, and senders. Use this to find candidate files cheaply, then call tool_get_attachment for one specific attachment. Use tool_fuzzy_search_messages when searching message text instead of attachment metadata.
tool_send_messageSend one outgoing message through the macOS Messages app.
This has an external side effect: it sends the provided text to the recipient using Messages. It may use iMessage or SMS/RCS depending on recipient availability and Messages configuration. Requires Automation permission for Messages, and the signed-in Mac must be able to send to the recipient. Returns a plain-text success or error message; it does not delete or modify existing conversations. Use tool_find_contact first when a name is ambiguous, and tool_check_imessage_availability when delivery capability is uncertain.
BEFORE YOU INSTALL
11 tools when we connected. Ten tools are read-only; tool_send_message sends a real message.
All 6 documented clients run the server on your machine.
CONTEXT COST
Rated by the size of the 11 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
uvx mac-messages-mcp{
"mcpServers": {
"mac-messages": {
"command": "uvx",
"args": [
"mac-messages-mcp"
]
}
}
}claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcpCodex CLI, the Codex IDE extension and the ChatGPT desktop app on the same Mac share one configuration. Add this to ~/.codex/config.toml:
[mcp_servers.mac-messages]
command = "uvx"
args = ["mac-messages-mcp"]{
"servers": {
"mac-messages": {
"type": "stdio",
"command": "uvx",
"args": [
"mac-messages-mcp"
]
}
}
}{
"mcpServers": {
"mac-messages-mcp": {
"command": "uvx",
"args": [
"mac-messages-mcp"
]
}
}
}MCP servers
sparfenyuk
redhat-community-ai-tools
mario-andreschak