Apple Messages MCP

MCP server for Apple Messages on macOS.

Provides access to message history, conversation search, and sending via Messages.app. Requires Full Disk Access for history and Automation access for sending.

When to use

• Messages-only workflows
• Message history and sending without the all-in-one server
• Tighter app-level separation for permissions

What It Does

• List conversations with pagination
• Search messages and view attachment metadata
• Send and reply to messages
• Tool discovery helpers search_tools and get_tool_info for context-constrained clients
• Unread and recent conversation resources
• Health checks that separate history access from automation failures
• Permission recovery: messages_permission_guide, messages_recheck_permissions

Install On This Mac

uvx apple-messages-mcp

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

Install In AI Agents

{
  "mcpServers": {
    "apple-messages": {
      "command": "uvx",
      "args": ["apple-messages-mcp"],
      "env": {
        "APPLE_MESSAGES_MCP_SAFETY_MODE": "full_access"
      }
    }
  }
}

claude mcp add --transport stdio --scope project apple-messages -- uvx apple-messages-mcp

Transport

stdio is the default and recommended transport. Set APPLE_MESSAGES_MCP_TRANSPORT=streamable-http (with optional APPLE_MESSAGES_MCP_HOST and APPLE_MESSAGES_MCP_PORT) to serve Streamable HTTP instead.

macOS Permissions

• Automation access to Messages is required for send and reply
• Full Disk Access is required for history, search, and attachment metadata from ~/Library/Messages/chat.db
• messages_health checks running state through NSRunningApplication, without sending Apple Events or requesting Automation access. Closed Messages reports automation_access_status: "not_probed"; running Messages reports "unknown". Neither means permission was denied.
• The existing automation_access and send-capability booleans are false when authorization is unverified. Explicit send tools still work when the user has authorized the operation. automation_access_status and automation_access_error_code distinguish skipped checks, unknown authorization, denial, and command failure. An explicit send or reply still checks authorization and may open Messages or show the macOS permission prompt.
• Diagnostic subprocesses have a five-second timeout. Explicit automation has a 30-second timeout; check delivery before retrying a send that timed out.

Launch Checklist

• Add uvx apple-messages-mcp (or a clone's AppleMessages-MCP/start.sh) to your MCP client
• Reload or reconnect the client so the Messages tool surface is loaded into context
• Call messages_health first
• If either permission surface is blocked, call messages_permission_guide
• After changing macOS permissions, call messages_recheck_permissions

Prompting Notes

• tools/list returns the full Messages tool surface. Context-constrained clients can use search_tools first, then get_tool_info for the Messages tool they need.
• Resolve the recipient via Contacts before any send or reply when the user names a person.
• Confirm the intended person if Contacts returns multiple matches.
• Omit service_name on iMessage sends. Passing it can trigger AppleScript error -1728.

Related

• Apple-Tools-MCP