Apple Messages · mgcrea — Claude Code MCP server: setup and message access
This MCP server lets agents search and read Apple Messages chats on macOS, covering iMessage, SMS, and RCS. Sending is off by default.
claude mcp add --env APPLE_MESSAGES_ALLOW_WRITES=<APPLE_MESSAGES_ALLOW_WRITES> --env APPLE_MESSAGES_ALLOW_CODES=<APPLE_MESSAGES_ALLOW_CODES> --env APPLE_MESSAGES_ALLOW_FILE_SEND=<APPLE_MESSAGES_ALLOW_FILE_SEND> --transport stdio messages -- npx -y @mgcrea/mcp-apple-messagesWhat Apple Messages does
Apple Messages gives an agent read access to the message store on a Mac. Its tools cover diagnostics, chat and message listings, text search, single-message retrieval, and counts grouped by date, chat, contact handle, or direction. Message content is recovered from attributedBody, while contact names are resolved through @mgcrea/mcp-apple-contacts.
The send_message tool can write to an existing chat after APPLE_MESSAGES_ALLOW_WRITES is enabled. File transfers through filePath need the separate APPLE_MESSAGES_ALLOW_FILE_SEND setting, and code lookup is gated by APPLE_MESSAGES_ALLOW_CODES. Full Disk Access is mandatory, so the server will not operate without that macOS permission.
What it helps with
- search message history by text
- read messages from a selected chat
- count messages by date or direction
- resolve phone handles to contact names
- send a message to an existing chat
Example prompts for the agent
- Search Apple Messages for messages about the order from last month.
- Show the latest messages in this chat and group the count by direction.
- Send the text from
release-notes.mdto the selected chat.
How to install Apple Messages
Platform CLI
claude mcp add --env APPLE_MESSAGES_ALLOW_WRITES=<APPLE_MESSAGES_ALLOW_WRITES> --env APPLE_MESSAGES_ALLOW_CODES=<APPLE_MESSAGES_ALLOW_CODES> --env APPLE_MESSAGES_ALLOW_FILE_SEND=<APPLE_MESSAGES_ALLOW_FILE_SEND> --transport stdio messages -- npx -y @mgcrea/mcp-apple-messagesReplace <…> with your own values
Platform CLI
codex mcp add messages --env APPLE_MESSAGES_ALLOW_WRITES=<APPLE_MESSAGES_ALLOW_WRITES> --env APPLE_MESSAGES_ALLOW_CODES=<APPLE_MESSAGES_ALLOW_CODES> --env APPLE_MESSAGES_ALLOW_FILE_SEND=<APPLE_MESSAGES_ALLOW_FILE_SEND> -- npx -y @mgcrea/mcp-apple-messagesReplace <…> with your own values
Config file
{
"mcpServers": {
"messages": {
"command": "npx",
"args": [
"-y",
"@mgcrea/mcp-apple-messages"
],
"env": {
"APPLE_MESSAGES_ALLOW_WRITES": "<APPLE_MESSAGES_ALLOW_WRITES>",
"APPLE_MESSAGES_ALLOW_CODES": "<APPLE_MESSAGES_ALLOW_CODES>",
"APPLE_MESSAGES_ALLOW_FILE_SEND": "<APPLE_MESSAGES_ALLOW_FILE_SEND>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"messages": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mgcrea/mcp-apple-messages"
],
"env": {
"APPLE_MESSAGES_ALLOW_WRITES": "<APPLE_MESSAGES_ALLOW_WRITES>",
"APPLE_MESSAGES_ALLOW_CODES": "<APPLE_MESSAGES_ALLOW_CODES>",
"APPLE_MESSAGES_ALLOW_FILE_SEND": "<APPLE_MESSAGES_ALLOW_FILE_SEND>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e APPLE_MESSAGES_ALLOW_WRITES=<APPLE_MESSAGES_ALLOW_WRITES> -e APPLE_MESSAGES_ALLOW_CODES=<APPLE_MESSAGES_ALLOW_CODES> -e APPLE_MESSAGES_ALLOW_FILE_SEND=<APPLE_MESSAGES_ALLOW_FILE_SEND> messages npx -y @mgcrea/mcp-apple-messagesReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Apple Messages
How do I install Apple Messages in Claude Code?
Run claude mcp add mcp-apple-messages -- npx -y @mgcrea/mcp-apple-messages. Then grant the server Full Disk Access in macOS.
What does Apple Messages do?
It lets an agent inspect chats and message text, search the store, resolve contact names, and produce grouped message counts. Sending is a separate opt-in capability.
What does Apple Messages need to run?
The server works with the Apple Messages store on macOS and requires Full Disk Access. Contact name resolution uses @mgcrea/mcp-apple-contacts; without Contacts permission, handles stay in their raw form.
Similar MCP servers
MCP servers catalog →Apple Messages by other authors comes first.
