messages — Claude Code MCP server: Apple Messages search
Search and browse your Apple Messages history from the terminal or through an AI agent. Useful when you need to recall what was agreed in a chat.
claude mcp add messages -- npx -y @cardmagic/messagesWhat messages does
The server opens the Apple Messages database and creates two search indexes over it: SQLite FTS5 for full-text lookup and MiniSearch for fuzzy matching that tolerates typos. The index rebuilds itself once new messages appear. Contact names come from the Address Book, so you see people rather than phone numbers.
Queries can be limited by sender and date, and each hit can bring a few surrounding messages for context. Beyond search you get recent messages, contacts sorted by activity and full threads. Every action is reachable from the command line, as MCP tools, or through a Claude plugin that ships slash commands such as /messages:search.
It is macOS-only because the data lives in ~/Library/Messages/chat.db. You need Node.js 22 or later and Full Disk Access granted to your terminal, or the database cannot be read at all. Index files sit in ~/.messages/.
What it helps with
- find what was agreed in a chat without scrolling through it
- see recent messages and who wrote last
- pull a full thread with one person over a date range
- locate a message when the search term has a typo
- spot the contacts you text most
Example prompts for the agent
- Look through my messages for what Mom said about dinner
- Show recent messages from John in December
- Who has texted me lately?
How to install messages
Platform CLI
claude mcp add messages -- npx -y @cardmagic/messagesPlatform CLI
codex mcp add messages -- npx -y @cardmagic/messagesConfig file
{
"mcpServers": {
"messages": {
"command": "npx",
"args": [
"-y",
"@cardmagic/messages"
]
}
}
}Config file
{
"servers": {
"messages": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cardmagic/messages"
]
}
}
}Platform CLI
gemini mcp add messages npx -y @cardmagic/messagesStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about messages
How do I install messages in Claude Code?
Run claude mcp add messages -- npx -y @cardmagic/messages. For the plugin with an auto-invoked skill and slash commands, run claude plugin marketplace add cardmagic/ai-marketplace, then claude plugin install messages@cardmagic.
What does messages do?
It searches your Apple Messages history with typo tolerance, and lists recent messages, contacts and threads. You can use it from the CLI, as an MCP server or as a Claude plugin.
What does messages require?
macOS, Node.js 22 or newer, and Full Disk Access for your terminal. Without that permission the tool cannot read ~/Library/Messages/chat.db.
