claude-history-mcp

MCP server that makes your Claude conversation history searchable. Export your conversations from 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

Setup

1. Export your Claude history

Go to claude.ai → Settings → Export Data. You'll receive an email with a download link containing a folder with conversations.json.

2. Clone and ingest

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:

{
  "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:

{
  "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:

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.