get_message_stats
Get statistics about the indexed messages including count, date range, and contacts.
LABSCO SUMMARY
A half-remembered text becomes findable by what was said rather than by when it was said.
Fuzzy matching plus the from, after and context parameters is what separates this from scrolling: you can search on a fragment, restrict it to one sender, and get the surrounding messages back with the hit. get_message_stats is the honest companion to that — it reports the count, date range and contacts in the index, so an empty result can be told apart from a gap in coverage. Every tool reads; nothing in the list sends a message or edits one.
What it is
A read-only search layer over an index of the local Apple Messages history, covering both iMessage and SMS.
What you get
- Fuzzy search across iMessage and SMS by text, by sender, or both, with a context window around each hit and an after date filter
- The most recent messages across every conversation, for the question of who has been in touch
- Contacts ranked by recent messaging activity, with message counts and the date of the last message
- Conversation threads listed with counts and a preview of the last message, sorted by recency
- A full thread with one contact in chronological order
- Statistics on the indexed set: message count, date range and contacts covered
Requirements
The Apple Messages history on the machine the server runs on, already indexed. No account and no key are configured, and the tools reach nothing off the machine.
Setup effort
One command — npx -y @cardmagic/messages --mcp
USE CASES
01
Finding the message where someone sent you the address
Search on the fragment you remember, narrow it to the sender if you know who it was, and open the thread around the hit to read what came next.
02
Working out who you have left on read
Look at the most recent messages across every conversation and the thread list with its previews, and see where the last message was theirs rather than yours.
03
Pulling one person's whole exchange for reference
Find the contact in the activity-ranked list to confirm the name and how much there is, then read the thread in order.
04
Telling an empty result apart from a gap in the index
Check the count, date range and contacts actually indexed before concluding that a conversation was never had.
6 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_thread
Get the full conversation thread with a specific contact. Shows messages in chronological order.
list_contacts
List contacts sorted by recent messaging activity. Shows contact name, message count, and last message date.
list_conversations
List conversations with message counts and last message preview. Shows all chat threads sorted by recent activity.
recent_messages
Get the most recent messages across all conversations. Use this to see "who texted me recently" or get an overview of recent activity.
search_messages
Search through Apple Messages (iMessage/SMS) with fuzzy matching. Can search by text query, filter by sender, or both. Use "from" to get messages from a specific person.
BEFORE YOU INSTALL
What to know first
Tools you get
6 tools when we connected.
Requires
- npx on PATH
- Node.js 22+
CONTEXT COST
Light Standing cost
Rated by the size of the 6 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"messages": {
"command": "npx",
"args": [
"-y",
"@cardmagic/messages",
"--mcp"
]
}
}
}npx
TERMINAL
npx -y @cardmagic/messages --mcp
