Enables an AI client to fuzzy search, browse, and retrieve Apple Messages and iMessage history from macOS.
Also known as cardmagic/messages, @cardmagic/messages
- Stars
- 20
- Tools
- 6
- Downloads, 30 days
- 275
- Latest version
- 1.2.0
- Last commit
- Nov 14, 2026
- License
- MIT
What is messages MCP?
messages enables an AI client to fuzzy search, browse, and retrieve Apple Messages and iMessage history from macOS. It exposes 6 tools, such as search_messages, recent_messages, list_contacts.
Summary generated from the project's README
About messages MCP server
Accessing your iMessage and SMS history through an AI client is what this server enables for macOS users. It allows an AI to perform fuzzy searches with typo tolerance, browse recent conversations, and resolve phone numbers into contact names. By connecting to your local Apple Messages database, the server provides a way to retrieve specific message threads or filter communications by sender and date range.
Developers can use this as a standalone command line interface, a Claude Code plugin, or a standard MCP server. Setting it up requires Node.js 22+ and granting Full Disk Access to your terminal application so it can read the chat.db file located in your Library folder. The system automatically builds and updates indexes to ensure searches remain fast and accurate as new messages arrive.
What you can do with it
- 1Find specific past conversationsAsk the AI to find a message about a specific topic like coffee or a trip using fuzzy matching.
- 2Review recent communicationsRequest a summary of who has texted you most recently to catch up on activity.
- 3Retrieve full message threadsAsk the AI to pull a complete conversation history with a specific contact after a certain date.
- 4Filter messages by senderInstruct the AI to look for specific keywords only within messages sent by a particular person.
Written from the project's README. Every use case is checked against a quote from it.
How to install messages MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall messages MCP in Claude Code
$ claude mcp add messages -- npx -y @cardmagic/messages mcpInstall messages MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"messages": {
"command": "npx",
"args": [
"-y",
"@cardmagic/messages",
"mcp"
]
}
}
}Install messages MCP in VS Code
.vscode/mcp.json
{
"servers": {
"messages": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cardmagic/messages",
"mcp"
]
}
}
}Install messages MCP in VS Code CLI
$ code --add-mcp '{"name":"messages","type":"stdio","command":"npx","args":["-y","@cardmagic/messages","mcp"]}'Install messages MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"messages": {
"command": "npx",
"args": [
"-y",
"@cardmagic/messages",
"mcp"
]
}
}
}Install messages MCP in Codex
$ codex mcp add messages -- npx -y @cardmagic/messages mcpInstall messages MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.messages] command = "npx" args = ["-y", "@cardmagic/messages", "mcp"]
Install messages MCP in Gemini CLI
$ gemini mcp add -s user messages npx -- -y @cardmagic/messages mcpInstall messages MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"messages": {
"command": "npx",
"args": [
"-y",
"@cardmagic/messages",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @cardmagic/messages 1.2.0 in an isolated container with no network and no keys. It answered and listed 6 tools.
messages MCP tools 6
Read from the server with tools/listsearch_messagesSearch 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.
recent_messagesGet the most recent messages across all conversations. Use this to see "who texted me recently" or get an overview of recent activity.
list_contactsList contacts sorted by recent messaging activity. Shows contact name, message count, and last message date.
list_conversationsList conversations with message counts and last message preview. Shows all chat threads sorted by recent activity.
get_threadGet the full conversation thread with a specific contact. Shows messages in chronological order.
get_message_statsGet statistics about the indexed messages including count, date range, and contacts.
| 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. | |
| 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. | |
| 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. | |
| get_thread | Get the full conversation thread with a specific contact. Shows messages in chronological order. | |
| get_message_stats | Get statistics about the indexed messages including count, date range, and contacts. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubmessages
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
brew install cardmagic/tap/messages
npm
npm install -g @cardmagic/messages
Claude Code Plugin (recommended)
Install as a plugin to get skills (auto-invoked) and slash commands:
# Add the marketplace
claude plugin marketplace add cardmagic/ai-marketplace
# Install the plugin
claude 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:
claude mcp add --transport stdio messages -- npx -y @cardmagic/messages --mcp
Or install globally first:
npm install -g @cardmagic/messages
claude mcp add --transport stdio messages -- messages --mcp
From source
git clone https://github.com/cardmagic/messages.git
cd messages
make install
# Then add as 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
Granting Full Disk Access
The tool needs to read your Messages database at ~/Library/Messages/chat.db:
- Open System Settings > Privacy & Security > Full Disk Access
- Click + and add your terminal app (Terminal.app, iTerm, Warp, etc.)
- Restart your terminal
Usage
CLI
Browse Commands
# Show most recent messages (who texted me?)
messages recent
# List contacts by recent activity
messages contacts --limit 10
# List conversations with message counts
messages conversations
# Show recent messages from someone
messages from "Mom"
# Show full conversation thread
messages thread "John" --after 2024-12-01
Search Commands
# Search for messages (index auto-builds on first search)
messages search "coffee tomorrow"
# Filter by sender
messages search "dinner" --from "Mom"
# Filter by date
messages search "meeting" --after 2024-01-01
# Adjust result count and context
messages search "project" --limit 20 --context 5
# Show index statistics
messages stats
# Force rebuild the index
messages index
Search Options
| Option | Description |
|---|---|
-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:
| Command | Description |
|---|---|
/messages:search <query> |
Fuzzy search with optional filters |
/messages:recent |
Show most recent messages |
/messages:contacts |
List contacts by activity |
/messages:conversations |
List 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:
| Tool | Description |
|---|---|
search_messages |
Search messages with fuzzy matching |
recent_messages |
Get most recent messages |
list_contacts |
List contacts by activity |
list_conversations |
List conversations with counts |
get_thread |
Get conversation thread with a contact |
get_message_stats |
Get index statistics |
Manual MCP Configuration
For Claude Desktop or VS Code, add to your MCP configuration:
{
"mcpServers": {
"messages": {
"command": "npx",
"args": ["-y", "@cardmagic/messages", "--mcp"]
}
}
}
How It Works
-
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
-
Searching: Queries both indexes for best results with typo tolerance
-
Storage: Index files are stored in
~/.messages/:index.db- SQLite FTS5 databasefuzzy.json- MiniSearch indexstats.json- Index statistics
License
MIT
messages MCP questions
How do I add messages MCP to Claude Code?
Run claude mcp add messages -- npx -y @cardmagic/messages mcp in your terminal. Add --scope user to make it available in every project.
How do I add messages MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does messages MCP provide?
It exposes 6 tools, including search_messages, recent_messages, list_contacts, list_conversations, get_thread.
What are the system requirements for this server?
You must be using macOS and have Node.js 22 or higher installed.
Do I need to grant any special permissions?
Yes, you must grant Full Disk Access to your terminal application in System Settings to allow the tool to read the Messages database.
How does the search indexing work?
The tool automatically builds a SQLite FTS5 full-text search index and a MiniSearch fuzzy search index when messages are detected.