Conversation Search MCP Server

A Model Context Protocol (MCP) server that provides comprehensive search and analysis capabilities for Claude Code conversation history.

Features

🔍 Full-Text Search

• Fast SQLite FTS (Full-Text Search) with optimized indexes

• Role-based filtering (user, assistant, system)

• Session and project-based organization

• Conversation naming and management

🧠 Vector Similarity Search (Optional)

• Semantic search using OpenAI embeddings

• Find conceptually related conversations

• Hybrid search combining keyword and semantic matching

• Configurable semantic vs keyword weighting

📊 Advanced Analytics

• Conversation indexing with metadata

• Usage statistics and database insights

• Incremental updates for new conversations

• Migration tools for vector database setup

🛠 Management Tools

• Automatic conversation discovery and indexing

• Custom conversation naming

• Session resume information

• Database health monitoring

Installation

Quick Start

1. Environment Setup (Optional for vector search):

   cp .env.example .env # Edit .env and add your OpenAI API key for vector search features

2. Initialize Database:

   # The server will automatically create the database on first run conversation-search-mcp

3. Index Conversations: Use the update_database tool to scan and index your Claude Code conversations.

Configuration

Environment Variables

• OPENAI_API_KEY - OpenAI API key for vector embeddings (optional)

• CONVERSATION_DB_PATH - Custom database path (defaults to ~/Sync/conversations.db)

• CLAUDE_DIR - Claude projects directory (defaults to ~/.claude/projects)

MCP Server Configuration

Add to your MCP settings:

Available Tools

Core Search Tools

• search_conversations - Full-text search through conversation history

• get_recent_conversations - Get recent conversations with metadata

• get_conversation_details - Detailed view of specific conversations

• get_session_for_resume - Information for resuming conversations

Management Tools

• rename_conversation - Assign custom names to conversations

• update_database - Full conversation indexing

• update_database_incremental - Incremental updates

• get_indexing_stats - Database statistics

Vector Search Tools (Requires OpenAI API Key)

• vector_search_conversations - Semantic similarity search

• hybrid_search_conversations - Combined keyword + semantic search

• migrate_to_vector_database - Vector database setup and migration

Usage Examples

Basic Text Search

Semantic Search

Hybrid Search

Project-Specific Search

Database Schema

The server maintains several SQLite tables:

• conversations - Main conversation data with FTS indexes

• conversation_names - Custom conversation names

• indexing_metadata - Indexing timestamps and metadata

• conversations_fts - Full-text search virtual table

Performance

• Fast Indexing: Optimized SQLite indexes for quick searches

• Incremental Updates: Only process new conversations

• Memory Efficient: Streaming processing for large datasets

• Batch Operations: Efficient bulk operations for initial indexing

Vector Search Costs

When using OpenAI embeddings:

• Text embedding model: text-embedding-ada-002

• Cost: ~$0.0001 per 1K tokens

• Use estimate_cost_only: true in migration tools to preview costs

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and feature requests, please use the GitHub issues page.