# claude-history-mcp

MCP server that makes your Claude conversation history searchable. Export your conversations from [claude.ai](https://claude.ai), ingest them into a local SQLite database with full-text search, and query them from Claude Code or Claude Desktop.

## Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)

## Setup

### 1. Export your Claude history

Go to [claude.ai](https://claude.ai) → Settings → Export Data. You'll receive an email with a download link containing a folder with `conversations.json`.

### 2. Clone and ingest

```bash
git clone https://github.com/fifeek0/claude-history-mcp.git
cd claude-history-mcp

# Ingest exported conversations into a local SQLite database
uv run python -m claude_history.ingest /path/to/exported/data/
```

This creates `history.db` in the project root with FTS5 full-text search indexes.

### 3. Configure as MCP server

#### Claude Code

Add to `~/.claude/.mcp.json`:

```json
{
  "mcpServers": {
    "claude-history": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/claude-history-mcp", "python", "-m", "claude_history"]
    }
  }
}
```

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "claude-history": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/claude-history-mcp", "python", "-m", "claude_history"]
    }
  }
}
```

Config file location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `search_history` | Full-text search across all messages. Supports FTS5 syntax (`AND`, `OR`, `NOT`, `"phrases"`). Optional topic filter. |
| `get_conversation_messages` | Get full conversation content with pagination (20 messages per page). |
| `list_all_topics` | List topic categories with conversation and message counts. |
| `browse_conversations` | Browse conversations by topic, sorted by date or size. |
| `conversation_summary` | Quick overview: stats, first and last human message. |

## Customizing Topic Classification

Topics are assigned by keyword matching during ingestion. Edit `src/claude_history/classify.py` to customize the `TOPIC_RULES` dictionary:

```python
TOPIC_RULES = {
    "Your Topic": ["keyword1", "keyword2", ...],
    ...
}
```

After editing, re-run the ingest command to reclassify all conversations.

## Re-ingesting

Running ingest again deletes the existing database and rebuilds it from scratch — safe to re-run after a fresh export or after changing classification rules.