home / mcp / messages mcp server

Messages MCP Server

Provides fuzzy search and browse access to Apple Messages via MCP for fast querying and conversation retrieval.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can search and browse your Apple Messages (iMessage and SMS) from the command line, or expose this capability as an MCP server that Claude Code or other MCP clients can talk to. This server provides fuzzy search with context, contact resolution, and convenient browse commands to quickly find conversations, messages, and threads.

How to use

You interact with the Messages MCP server from an MCP client or Claude Code. The server exposes tools that let you search messages with typo tolerance, view recent messages, and fetch full conversation threads. Use the provided tools through an MCP client connection to perform fuzzy searches, list contacts by activity, and retrieve message threads.

How to install

Prerequisites you need before installing: macOS, Node.js 22 or newer, and Full Disk Access permission for your terminal so the server can read your Apple Messages database at ~/Library/Messages/chat.db.

Install the MCP server through the recommended channels or build from source as shown.

Option 1: Install via Claude Code Plugin and MCP (recommended to enable auto-invocation and slash commands) and connect to MCP as shown.

# Add the marketplace and install the plugin (Claude Code) 
claude plugin marketplace add cardmagic/ai-marketplace
claude plugin install messages@cardmagic

# Add as an MCP server (stdio transport) using the npx-based command
claude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp

# Or install globally and add as an MCP server using the binary command
npm install -g @cardmagic/messages
claude mcp add --transport stdio messages -- messages --mcp

Additional installation paths and options

Option 2: Install from source and set up as a plugin or as an MCP server. You can clone the project, install dependencies, and then configure MCP access.

git clone https://github.com/cardmagic/messages.git
cd messages
make install

# Then add as a plugin OR MCP server:
claude plugin marketplace add cardmagic/ai-marketplace
claude plugin install messages@cardmagic
# OR
claude mcp add --transport stdio messages -- messages --mcp

Notes on usage and capabilities

The server supports these core actions through the MCP interface: searching messages with fuzzy matching, listing recent messages, listing contacts by activity, listing conversations with counts, fetching a full thread with a contact, and retrieving index statistics. When you start using the MCP endpoint, you gain fast access to your entire Messages history with context around matches.

Security and access considerations

To read your Messages database securely, the server relies on your macOS permissions. Ensure you grant Full Disk Access to the terminal or launcher you use to run the MCP server. This access is limited to the Messages database used for indexing and search.

Troubleshooting

If you encounter issues starting the MCP server, verify that Node.js 22+ is installed, and that the terminal has the necessary Full Disk Access permissions. Also confirm the MCP transport is configured as stdio and that the command and arguments exactly match one of the npm/npx installation paths shown in the installation steps.

Available tools

search_messages

Fuzzy search messages with typo tolerance across your Messages database and return matching messages with context and optional sender filters.

recent_messages

Retrieve the most recent messages to browse recent activity.

list_contacts

List contacts by activity, showing the most engaged conversations and participants.

list_conversations

List conversations with message counts to understand communication volume and recent activity.

get_thread

Fetch the full message thread with a specific contact, including surrounding messages by optional date filters.

get_message_stats

Return index statistics to monitor index health and size.