Skip to content
MCP server

Apple Messages

Search and read iMessage, SMS and RCS history on a Mac, with sending off by default

Runs locallyStatus and history
Pricing
Open source
Platforms
macOS, CLI
Runs
Locally
Version
1.40.0
Listing updated
2 days ago

About Apple Messages

Apple Messages is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

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

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mcp-apple-messages": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-messages"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-apple-messages": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-messages"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • APPLE_MESSAGES_ALLOW_WRITESRegister the mutating tools. Off by default, and the gate decides whether the write tools exist at all rather than merely refusing — an agent with writes off cannot see them.
  • APPLE_MESSAGES_ALLOW_CODESRegister apple_messages_find_codes, which reads one-time codes out of recent messages. Its own gate rather than allowWrites: it is a read, and the one read most worth an explicit decision.
  • APPLE_MESSAGES_ALLOW_FILE_SENDLet apple_messages_send_message attach a local file. Off by default even with writes on, because a path argument is a way to send anything the server can read.

Tools this server provides (7)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Open source

MIT servers; the Cupertino menu-bar app has a 30-minute trial and 30-day refund, price not published

Prices change. Check cupertino.mgcrea.io before you buy.

Apple Messages 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 to Apple Messages

  1. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity
  2. Concord MCP

    MCP server

    Local-first MCP server for messaging and shared work-state between coding agents

    Runs locally
    • Freemium
    • 1.3K GitHub stars
    • Developer tools
  3. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity
  4. BoardAgent

    MCP server

    Remote MCP server for a message board where only AI agents post, reply and vote

    • 27 tools
    • Remote
    • Free
    • Community directories
  5. Callout

    MCP server

    Let an AI agent place real phone calls in Japanese or English and read the transcript

    • 5 tools
    • Remote
    • Freemium
    • Communication
  6. CalderFlow

    MCP server

    Turn notes or specs into editable flowcharts, timelines and funnels from an AI assistant

    • 10 tools
    • Remote
    • Free
    • Design and media