Claude Code Conversation Search MCP

Stop losing your Claude Code conversations. Never again ask "where did we discuss that bug fix?" or lose hours of context when your terminal closes.

npm install -g claude-code-conversation-search-mcp

Find any conversation across all projects:

"where did we discuss the database issue?"
"find that authentication conversation"
"docker configuration we talked about yesterday"

Get the exact project, date, and command to resume instantly.

Why You Need This

The Problem: Claude Code has no conversation search. When you close a terminal or switch projects, finding that important discussion becomes impossible. You're left scrolling through cryptic conversation titles hoping to recognize the right one.

The Solution: Search all your Claude Code conversations from any project session. Ask "where did we discuss authentication?" and instantly get the exact conversation with a resume command.

Features

• Find lost conversations: Never lose track of important discussions again
• Search across all projects: Working in Project A but need info from Project B? Just search
• Resume instantly: Get exact claude --resume commands to continue where you left off
• Natural language: Ask questions like you would a human - "find that Docker conversation"
• Lightning fast: Search thousands of conversations in milliseconds
• Zero setup: Install and it works immediately with your existing Claude Code

Quick Start

Install and it auto-configures with Claude Code:

npm install -g claude-code-conversation-search-mcp

Search across all projects while working in any project.

🎯 Recommended: Enhanced Claude Code Integration

For optimal search results and better Claude Code interaction, add these instructions to your global ~/.claude/CLAUDE.md file:

# Add to ~/.claude/CLAUDE.md
echo "- When asked to use conversation-search, you must start searching from very wide queries, narrowing down step by step. When responding based on this mcp results output a human readable text with proper newlines instead of formatting json." >> ~/.claude/CLAUDE.md

Why this helps:

• Better search strategy: Claude will start with broad queries and progressively narrow down, finding more relevant results
• Human-readable output: Instead of raw JSON, you'll get properly formatted responses with project paths, dates, and resume commands
• Improved UX: Makes conversation search feel natural and intuitive within Claude Code workflows

Usage

# Find lost conversations
"where did we discuss the login bug?"
"find that Docker conversation"
"database setup we talked about"

# Search by what you remember
"authentication error we fixed"
"API endpoint discussion yesterday"
"performance issue last week"

# Find solutions from other projects  
"how did we solve CORS issues?"
"Redis configuration that worked"
"deployment script we wrote"

Every search gives you:

• Which project the conversation was in
• When it happened (date and time)
• What you discussed (conversation summary)
• Smart shortcuts to resume: cd ~/.cs/project-name && claude --resume abc123

Smart Directory Shortcuts

The search automatically creates directory shortcuts for faster navigation:

• Cross-platform: Works on macOS, Linux, and Windows
• Short paths: Uses ~/.cs/ instead of long project paths
• Real directories: Creates actual symlinks/junctions you can cd into
• Project-based names: Uses meaningful names like poc-fbf-v023-1-cc
• Automatic creation: Generated on-demand during search

Example:

# Instead of:
cd '/Users/username/very/long/path/to/project'

# You get:
cd ~/.cs/project-name

Technical

Built with TypeScript, uses SQLite FTS5 for search, integrates via Model Context Protocol.

System requirements:

• Node.js 18+
• Claude Code with MCP support
• macOS, Linux, or Windows

Performance:

• Sub-second search across 10k+ conversations
• Real-time indexing with file watching
• Minimal memory footprint (~50MB)

Storage:

• SQLite database in ~/.claude/conversation-search/
• Indexes conversation content, not file contents
• Automatic cleanup of deleted conversations

Installation

From source

# Clone the repository
git clone https://github.com/TonySimonovsky/claude-code-conversation-search-mcp.git
cd claude-code-conversation-search-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Link globally
npm link

Configuration

Automatic Setup (Recommended)

After installation, the MCP server auto-configures with Claude Code. No manual configuration needed!

Manual Configuration (Optional)

If you need custom configuration, choose one of these approaches:

Option 1: Command Line (Recommended)

# Add globally for all projects
claude mcp add conversation-search claude-code-conversation-search-mcp

# Add for current project only (creates .mcp.json)
claude mcp add --scope project conversation-search claude-code-conversation-search-mcp

Option 2: Edit Configuration Files Directly

Global configuration (all projects):

# Edit the global Claude Code config (run from anywhere)
nano ~/.claude.json
# Or use your preferred editor: code ~/.claude.json

{
  "mcpServers": {
    "conversation-search": {
      "command": "claude-code-conversation-search-mcp",
      "args": []
    }
  }
}

Project-specific configuration (team-shared):

# Create project config file (run from project root)
nano .mcp.json
# Or: code .mcp.json

{
  "mcpServers": {
    "conversation-search": {
      "command": "claude-code-conversation-search-mcp",
      "args": []
    }
  }
}

Configuration Options

The MCP server supports extensive configuration through environment variables. Here are the most commonly used options:

Environment Variable	Description	Default
CONVERSATION_DB_PATH	Path to SQLite database	~/.claude/conversation-search.db
CLAUDE_PROJECTS_DIR	Path to Claude projects directory	~/.claude/projects
INDEX_INTERVAL	Auto-index interval in milliseconds	300000 (5 minutes)
MAX_RESULTS	Maximum search results to return	20
DEFAULT_CONTEXT_SIZE	Default context messages before/after	2
AUTO_INDEXING	Enable automatic indexing	true
DEBUG	Enable debug logging	false

📖 For complete configuration options and performance tuning, see Configuration Guide

Usage

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

Search Conversations

Search through your conversation history with natural language:

search_conversations("Where did we create auth.js?")
search_conversations("database optimization last week")
search_conversations("TypeError in index.ts")

Query Examples:

• File operations: "created auth.js", "edited config.json", "modified database.ts"
• Topics: "discuss React hooks", "security review", "performance optimization"
• Errors: "TypeError", "CORS error", "undefined variable"
• Commands: "npm install lodash", "git commit", "database migration"
• Time filters: "today", "yesterday", "last week", "this month"
• Project filters: "in project myapp", "from backend-api"

Parameters:

• query (required): Natural language search query
• limit (optional): Maximum results to return (default: 10)
• includeContext (optional): Include surrounding messages (default: true)

List Projects

Get all indexed projects with statistics:

list_projects()

Returns project names, message counts, and last activity dates.

Get Message Context

Retrieve full context around a specific message:

get_message_context("msg_abc123", contextSize: 5)

Parameters:

• messageId (required): The message ID to get context for
• contextSize (optional): Number of messages before/after (default: 5)

Get Conversation Messages

Retrieve messages from a specific conversation:

get_conversation_messages("conv_456", limit: 50, startFrom: 0)
get_conversation_messages("conv_456", limit: 10, startFrom: -1)  # Last 10 messages
get_conversation_messages("conv_456", limit: 20, startFrom: -10) # 20 messages starting from 10th from end

Parameters:

• conversationId (required): The conversation ID to get messages from
• limit (optional): Number of messages to return (default: 50)
• startFrom (optional): Starting position - 0=first, -1=last, -10=10th from end (default: 0)

List Tools

Show all available tools with their signatures:

list_tools()

Returns automatically generated tool signatures and descriptions. Updates automatically when new tools are added.

Refresh Index

Manually trigger re-indexing:

refresh_index()

Useful after adding new projects or when auto-indexing is disabled.

Get Server Information

Show server version, changelog, and system information:

get_server_info()

Displays current version, recent changes, system status, and available tools.

Advanced Usage

Complex Queries

Our built-in query parser supports sophisticated natural language patterns:

# Find specific file operations
"Where did we create or modify authentication files?"

# Search by multiple criteria
"database migrations in project backend last week"

# Find specific error patterns
"TypeError or ReferenceError in React components"

# Search tool operations
"bash commands containing npm or yarn"

# Find code discussions
"Where did we discuss implementing caching?"

Search Operators

• AND: Terms are ANDed by default ("auth login" finds messages with both)
• OR: Use "or" between terms ("auth or login")
• NOT: Use "-" prefix ("auth -test" excludes test-related results)
• Phrase: Use quotes for exact phrases ("user authentication")
• Wildcard: Use * for prefix matching ("auth*" matches auth, authentication, etc.)

Time Filters

Supported time expressions:

• today, yesterday
• last week, this week
• last month, this month
• last 7 days, last 30 days
• Specific dates: "on 2024-01-15", "since January 1"

Development

Setup Development Environment

# Clone and install
git clone <repository>
cd claude-code-conversation-search-mcp
npm install

# Run in development mode with hot reload
npm run dev

# Run tests
npm test

# Build for production
npm run build

Project Structure

src/
├── index.ts              # MCP server entry point
├── indexer/
│   ├── parser.ts        # JSONL conversation parser
│   ├── database.ts      # SQLite database operations
│   └── indexer.ts       # Indexing orchestration
├── search/
│   └── query.ts         # Natural language query parser
└── types/
    └── index.ts         # TypeScript type definitions

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Troubleshooting

Database Issues

If the search index becomes corrupted:

# Remove the database file
rm ~/.claude/conversation-search.db

# Restart Claude Code to trigger re-indexing

Performance Optimization

For large conversation histories:

1. Increase INDEX_INTERVAL to reduce indexing frequency
2. Set MAX_RESULTS to limit result size
3. Use specific project filters in queries

Debug Mode

Enable debug logging to troubleshoot issues:

{
  "mcpServers": {
    "conversation-search": {
      "command": "npx",
      "args": ["claude-code-conversation-search-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

License

MIT License - see LICENSE file for details

Acknowledgments

Built using the Model Context Protocol SDK by Anthropic.

Credits

Developed by Tony AI Champ & Claude Code, 09-2025

Support

For issues, feature requests, or questions:

• Open an issue on GitHub
• Check existing issues for solutions
• Include debug logs when reporting bugs