Messages

io.github.cardmagicPublished by GitHub account cardmagicv1.2.0Updated Oct 24, 2026

Fuzzy search and browse Apple Messages/iMessage from CLI or MCP server

VerifiedSTDIODesktop onlyKnowledge & MemoryCommunication & Collaboration

Overview

AI-generated overview

A local MCP server that lets an assistant fuzzy-search and browse your Apple Messages/iMessage history, contacts and conversations on a Mac.

What you can do
Search messages with fuzzy, typo-tolerant matching, optionally filtered by sender or date range and with surrounding context shown. Browse recent messages, contacts by activity, and conversations with message counts. Open a full conversation thread with a given contact. Report search index statistics.
When to use it
Useful when you want an assistant to answer questions about your own texts, such as what someone said about a plan, who messaged recently, or what was discussed in a thread, without copying messages by hand.
Requirements
macOS only, since it reads the Apple Messages database. Node.js 22+ and the npm package, run locally over stdio. Full Disk Access permission must be granted to your terminal app so it can read the Messages database.
Before you install
It reads your entire Messages history and Address Book contacts and builds local search indexes under your home directory, so anyone with access to that machine or those index files can see the content. Granting Full Disk Access to a terminal is broad; consider what else runs in that terminal. Read-only browsing, but highly personal data.

Installation

In SourceWeft

  1. Open Messages in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

messages

Fuzzy search and browse Apple Messages (iMessage/SMS) from the command line, as a Claude Code plugin, or as an MCP server.

Features

  • Fuzzy search with typo tolerance across all your messages
  • Browse recent messages, contacts, and conversations
  • Contact resolution - shows names instead of phone numbers
  • Context display - see messages before/after each match
  • Filter by sender or date range
  • Auto-indexing - index automatically rebuilds when new messages are detected
  • Multiple interfaces - CLI, MCP server, or Claude Code plugin

Requirements

  • macOS (reads from Apple Messages database)
  • Node.js 22+
  • Full Disk Access permission for your terminal (to read ~/Library/Messages/chat.db)

Installation

Homebrew

bash
brew install cardmagic/tap/messages

npm

bash
npm install -g @cardmagic/messages

Claude Code Plugin (recommended)

Install as a plugin to get skills (auto-invoked) and slash commands:

bash
# Add the marketplaceclaude plugin marketplace add cardmagic/ai-marketplace
# Install the pluginclaude plugin install messages@cardmagic

This gives you:

  • Skill: Claude automatically searches messages when you ask about texts/iMessages
  • Slash commands: /messages:search, /messages:recent, /messages:from, and more

MCP Server

For direct MCP tool access without the plugin:

bash
claude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp

Or install globally first:

bash
npm install -g @cardmagic/messagesclaude mcp add --transport stdio messages -- messages --mcp

From source

bash
git clone https://github.com/cardmagic/messages.gitcd messagesmake install
# Then add as plugin OR MCP server:claude plugin marketplace add cardmagic/ai-marketplaceclaude plugin install messages@cardmagic# ORclaude mcp add --transport stdio messages -- messages --mcp

Granting Full Disk Access

The tool needs to read your Messages database at ~/Library/Messages/chat.db:

  1. Open System Settings > Privacy & Security > Full Disk Access
  2. Click + and add your terminal app (Terminal.app, iTerm, Warp, etc.)
  3. Restart your terminal

Usage

CLI

Browse Commands
bash
# Show most recent messages (who texted me?)messages recent
# List contacts by recent activitymessages contacts --limit 10
# List conversations with message countsmessages conversations
# Show recent messages from someonemessages from "Mom"
# Show full conversation threadmessages thread "John" --after 2024-12-01
Search Commands
bash
# Search for messages (index auto-builds on first search)messages search "coffee tomorrow"
# Filter by sendermessages search "dinner" --from "Mom"
# Filter by datemessages search "meeting" --after 2024-01-01
# Adjust result count and contextmessages search "project" --limit 20 --context 5
# Show index statisticsmessages stats
# Force rebuild the indexmessages index
Search Options
OptionDescription
-f, --from <sender>Filter by sender name or phone
-a, --after <date>Only messages after date (YYYY-MM-DD)
-l, --limit <n>Max results (default: 10)
-c, --context <n>Messages before/after (default: 2)

Claude Code Plugin

When installed as a plugin, you get:

Skill (auto-invoked): Claude automatically searches messages when you ask things like:

  • "What did Mom say about dinner?"
  • "Who texted me recently?"
  • "Find messages about the trip"

Slash Commands:

CommandDescription
/messages:search <query>Fuzzy search with optional filters
/messages:recentShow most recent messages
/messages:contactsList contacts by activity
/messages:conversationsList conversations with message counts
/messages:from "Name"Messages from a specific person
/messages:thread "Name"Full conversation thread
/messages:browse <cmd>Alias for browse commands

MCP Server

When installed as an MCP server, Claude Code can use these tools:

ToolDescription
search_messagesSearch messages with fuzzy matching
recent_messagesGet most recent messages
list_contactsList contacts by activity
list_conversationsList conversations with counts
get_threadGet conversation thread with a contact
get_message_statsGet index statistics
Manual MCP Configuration

For Claude Desktop or VS Code, add to your MCP configuration:

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

How It Works

  1. Auto-Indexing: On first search (or when new messages are detected), the tool automatically:

    • Reads your Apple Messages SQLite database
    • Builds a SQLite FTS5 full-text search index
    • Creates a MiniSearch fuzzy search index
    • Resolves contact names from your Address Book

  2. Searching: Queries both indexes for best results with typo tolerance

  3. Storage: Index files are stored in ~/.messages/:

    • index.db - SQLite FTS5 database
    • fuzzy.json - MiniSearch index
    • stats.json - Index statistics

License

MIT

Source: README.md at commit e3fa952

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.2.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts