Conversation History

A local MCP server that indexes and searches your Claude Code conversation history with both keyword and semantic search.

Features

• Keyword Search - Fast full-text search using SQLite FTS5
• Semantic Search - Find conceptually similar conversations using local embeddings
• Session Listing - Browse recent sessions with summaries
• Context Retrieval - Get full context from any past conversation
• Fully Private - All data stays local, no external API calls

Installation

Prerequisites

• Python 3.10+
• Claude Code CLI

Quick Install

# Clone the repo
git clone https://github.com/SDillon001/conversation-history-mcp.git
cd conversation-history-mcp

# Install dependencies
pip install -r requirements.txt

# Create symlink to Claude's MCP directory
mkdir -p ~/.claude/mcp-servers
ln -s "$(pwd)" ~/.claude/mcp-servers/conversation-history

# Add to Claude Code settings
# See Configuration section below

Configuration

Add to your ~/.claude.json under the mcpServers key:

{
  "mcpServers": {
    "conversation-history": {
      "type": "stdio",
      "command": "python3",
      "args": ["server.py"],
      "cwd": "/path/to/conversation-history-mcp"
    }
  }
}

Replace /path/to/conversation-history-mcp with the actual path to your installation.

Usage

Once configured, the following tools are available in any Claude Code session:

search_sessions

Keyword search across all conversation history.

"Search for conversations about authentication"
→ Claude calls search_sessions(query="authentication")

search_semantic

Semantic search to find conceptually similar conversations.

"Find conversations similar to database optimization"
→ Claude calls search_semantic(query="database optimization")

list_sessions

List recent sessions with summaries.

"What did I work on last week?"
→ Claude calls list_sessions(days=7)

get_session

Get full context from a specific session.

"Show me the full conversation from session abc123"
→ Claude calls get_session(session_id="abc123")

rebuild_index

Force rebuild the search index (usually not needed).

"Rebuild the conversation index"
→ Claude calls rebuild_index()

How It Works

1. Indexing - On startup, the server scans ~/.claude/projects/ for JSONL session files
2. FTS5 - Messages are indexed in SQLite with full-text search
3. Embeddings - Using sentence-transformers/all-MiniLM-L6-v2 (runs locally)
4. Incremental - Only new sessions are indexed after first run

Data Storage

~/.claude/mcp-servers/conversation-history/
└── data/
    ├── index.db      # SQLite with FTS5 (keyword search)
    └── chroma/       # ChromaDB (semantic search embeddings)

Your conversation history stays in ~/.claude/projects/ - this server only creates a search index.

Privacy

• No external API calls - Embeddings generated locally
• No data leaves your machine - Everything stays in ~/.claude/
• Read-only access - Server only reads session files, never modifies them

Development

# Run server directly for testing
python server.py

# Run tests
pytest tests/

License

MIT