# messages

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 20
- Author: cardmagic
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cardmagic/messages
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/messages

## What it 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/`.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add messages -- npx -y @cardmagic/messages
```

### Codex

**Platform CLI**
```bash
codex mcp add messages -- npx -y @cardmagic/messages
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "messages": {
            "command": "npx",
            "args": [
                "-y",
                "@cardmagic/messages"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "messages": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@cardmagic/messages"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add messages npx -y @cardmagic/messages
```

## When to use it
- 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
- Look through my messages for what Mom said about dinner
- Show recent messages from John in December
- Who has texted me lately?

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md