# Apple Messages

> Apple Messages is an open-source MCP server for communication. Search and read iMessage, SMS and RCS history on a Mac, with sending off by default. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, CLI
- **Website:** https://cupertino.mgcrea.io
- **Repository:** https://github.com/mgcrea/cupertino/tree/HEAD/packages/messages
- **MCP Registry name:** io.github.mgcrea/mcp-apple-messages
- **Categories:** communication, productivity
- **Listing updated:** 2026-11-14

## About

This is the Cupertino surface with only one way in. Messages' scripting dictionary fails every read, so Full Disk Access is mandatory and nothing works without it. Apple Events is used only to send, so with writes off no Apple Event is ever sent and no Automation grant is requested.

A notable detail from the README: message text lives in two places in the chat database, and from March 2026 on every message is stored only in an attributedBody blob. The server includes a decoder, reported to agree with plain text on all 94,043 labelled rows of a 97,416-message test store, so recent conversations are not silently empty.

Names are resolved through the Contacts server; an unresolved handle is normal, not an error. Reading one-time codes (APPLE_MESSAGES_ALLOW_CODES) and attaching files to a send (APPLE_MESSAGES_ALLOW_FILE_SEND) each need their own switch. It is unofficial and MIT licensed.

## Features

- **Decodes recent messages:** Reads blob-only text that plain SQL misses.
- **Contact name resolution:** Maps phone numbers to names via the Contacts server.
- **Send gate:** Sending is unregistered until writes are enabled.
- **Separate code reading:** One-time codes need their own opt-in.
- **File send gate:** Attachments stay off even with writes on.

## Good for

- Find what someone texted months ago
- Summarise a group chat for a handover
- Get an agent to draft and send a reply you approve
- Count messages in a conversation

## Install

### Claude Code (Terminal)

```sh
claude mcp add mcp-apple-messages -- npx -y @mgcrea/mcp-apple-messages
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mcp-apple-messages": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-messages"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mcp-apple-messages": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-messages"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mcp-apple-messages": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-messages"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "mcp-apple-messages": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-messages"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "mcp-apple-messages": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-messages"
      ]
    }
  }
}
```

## Tools

- `apple_messages_diagnostics`: Reports which access paths work.
- `apple_messages_list_chats`: Lists chats.
- `apple_messages_list_messages`: Lists messages in a chat.
- `apple_messages_search_messages`: Searches message text.
- `apple_messages_get_message`: Fetches one message.
- `apple_messages_find_codes`: Reads one-time codes from recent messages.
- `apple_messages_send_message`: Sends a message when writes are enabled.

## FAQ

### Can it work without Full Disk Access?

No. There is no degraded mode.

### Is it affiliated with Apple?

No, it is unofficial.

### Does it cover SMS and RCS?

Yes, alongside iMessage.

### Can the agent send messages by default?

No, sending needs APPLE_MESSAGES_ALLOW_WRITES.

### Is Apple Messages free?

Yes. Apple Messages is open source, so you can use and self-host it for free.

### How do I add Apple Messages to Claude Code?

Run this command in your terminal: claude mcp add mcp-apple-messages -- npx -y @mgcrea/mcp-apple-messages

### What are the best alternatives to Apple Messages?

The closest alternatives to Apple Messages are Ha MCP, Concord MCP, note1, BoardAgent and Callout.

## Alternatives

- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [BoardAgent](https://ai-powered.com/mcp/boardagent): BoardAgent is a free MCP server for community directories.
- [Callout](https://ai-powered.com/mcp/callout): Callout is a freemium MCP server for communication.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [nicemails](https://ai-powered.com/mcp/nicemails): nicemails is a freemium MCP server for communication.
- [SOMMON Office](https://ai-powered.com/mcp/sommon-office): SOMMON Office is a paid MCP server for communication.

---
Source: https://ai-powered.com/mcp/apple-messages-2
