Mac Messages MCP
An MCP server for macOS: an agent reads, searches and sends messages in the Messages app on your Mac
- 339 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Reads your private conversations and contacts from macOS databases
- The send and scheduled-send tools write to real people in your name
- Work requires macOS system permissions for the launching app
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/mac-messages-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Reads your private conversations and contacts from macOS databases
- The send and scheduled-send tools write to real people in your name
- Work requires macOS system permissions for the launching app
This is third-party code. Review the repository files before installing.
What it does
Mac Messages MCP runs locally on your Mac and gives an MCP client access to the Messages app. It opens the Messages and Contacts databases read-only and returns only what the client asked for. The server turns on Messages.app automation only when the client explicitly calls the send tool. You can read recent messages by contact, group chat or date range, with paging. Text search is fuzzy, over a chosen period or all history. Separate tools find contacts by approximate name, find attachments and search text inside PDFs. Sending goes through iMessage, falling back to SMS or RCS. You can attach a file and turn on human approval through MCP. A message can be queued to send later. Text from messages and contacts reaches the model inside an untrusted-data fence. Three ready prompts and an agent skill come with it.
Who it is for. For Mac users who want to triage incoming messages, search conversations and reply through Claude, Codex or Cursor.
Good fit when
- You need to look through unread messages and get a short summary per person
- You need to find an agreement about a date in a conversation from an approximate phrase
- An agent drafts a reply and you approve sending in the client itself
- You need an attachment from a conversation, such as an invitation image or a PDF
Not a fit when
- You are not on macOS: the server works on a Mac only
- You need reactions, edits or deletion of messages: Messages.app automation does not offer them
- Your conversations must not be shown to a cloud model provider: found text goes into the agent's context
Example request
Show today's unread messages and write one line per person saying what they askMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
MAC_MESSAGES_REGION- ISO 3166-1 region code for parsing national numbers, for example GB
Limitations
macOS only. To read messages, the app that launches the client needs Full Disk Access. Sending works only when the Mac is signed in to Messages and Contacts and Messages are available to the launching app. Python 3.10 or newer is required, and uvx provisions it. You cannot send tapbacks, effects or a subject, create groups, or edit and delete messages. Scheduled messages are not saved to disk and vanish if the client disconnects.
How to disable. Remove the mac-messages entry from the client configuration; for Claude Code run claude mcp remove mac-messages. Then revoke Full Disk Access in macOS settings from the app you granted it to.
FAQ
How do I connect Mac Messages MCP to Claude Code?
Run claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcp. Check the connection with claude mcp get mac-messages or the /mcp command inside Claude Code.
Which other macOS permissions does the server need?
To send, the Mac must be signed in to Messages, and the launching app gets permission to control Messages.app. macOS asks for Contacts access separately on the first contact lookup.
In what format should I give a recipient?
Most reliable is an E.164 number such as +14155551234. A national format is expanded using your Mac's region, which you can set with MAC_MESSAGES_REGION. Email addresses, contact names and group chat IDs are accepted too.
Will an agent send a message without my knowledge?
Sending happens only through the tool_send_message call. You can require human approval for it through MCP, and the server's prompts never send anything.
How does the server guard against text inside messages?
Text from messages and contacts reaches the model inside an untrusted-data fence so someone else's message is not taken as an instruction.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server for your personal WhatsApp account: search and read chats, contacts, send messages and files through an agent
iMCP
imcp
A macOS app that opens the calendar, contacts, reminders, messages and other Mac data to AI through MCP. Not affiliated with Apple
Pachca MCP
mcp-pachca
MCP server for the Pachca corporate messenger: chats, message search, users and sending messages
An MCP server for Slack: channel history, threads, DMs, search and unreads, with posting off by default
An email MCP with 52 tools: the agent reads, searches, sends and sorts mail across several accounts over IMAP and SMTP, and schedules sends
MCP email server over IMAP and SMTP: an agent searches, reads, sorts and sends mail across several mailboxes
README in short
The documentation opens with a data flow diagram and walks through setting up five clients, from Claude Desktop to VS Code. The tool table marks each tool's side effects, and a separate part covers building the Claude Desktop extension.