Cowork History MCP

An MCP (Model Context Protocol) server for searching and browsing your Claude conversation history stored in ~/.claude/. Works with both Claude Code and Cowork conversations.

Features

• Hybrid Search - Combines multiple search methods for best results:
  • SQLite FTS5 - Fast full-text search with BM25 ranking
  • macOS Spotlight - Leverages system content indexing via mdfind
  • Vector Embeddings - Semantic similarity search (optional, requires Ollama)
• Smart Path Reconstruction - Recovers actual filesystem paths via probing (not heuristic guessing)
• Persistent Index - SQLite database with incremental updates for fast queries
• Ollama Setup Tools - Automated installation and configuration for embeddings

Installation

Option 1: Claude Desktop (One-Click Install)

Download cowork-history.mcpb from the latest release and double-click to install.

Option 2: Via uvx (Recommended for CLI)

uvx cowork-history

Option 3: Via pip

pip install cowork-history

Option 4: Manual Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cowork-history": {
      "command": "uvx",
      "args": ["cowork-history"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

Quick Start

Once installed, Claude can search your conversation history:

"What did we discuss about authentication last week?"
"Find the conversation where we debugged the payment webhook"
"Show me my conversations in the my-project folder"

Available Tools

Search & Browse

| Tool | Description | |------|-------------| | cowork_history_search | Search conversations using hybrid search (FTS + Spotlight + vector) | | cowork_history_list | List recent conversations, optionally filtered by project | | cowork_history_get | Get full content of a specific conversation by session ID | | cowork_history_projects | List all projects with conversation history | | cowork_history_stats | Get statistics and search capability status | | cowork_history_reindex | Rebuild index and optionally generate embeddings |

Ollama Setup (for Vector Search)

| Tool | Description | |------|-------------| | history_system_check | Check system requirements for Ollama | | history_setup_ollama | Install Ollama via Homebrew (macOS) | | history_setup_ollama_direct | Install Ollama via direct download (no Homebrew) | | history_ollama_status | Check Ollama status and embedding model availability |

Search Modes

The cowork_history_search tool supports multiple search modes:

| Mode | Description | |------|-------------| | auto (default) | Uses all available methods, best results | | fts | Full-text search only (fastest) | | spotlight | macOS Spotlight only | | vector | Semantic similarity only (requires Ollama) | | hybrid | Explicit combination with ranking |

Search Examples

"authentication bug"           → finds conversations with both words
"how to deploy"                → semantic search finds related discussions
"\"exact phrase\""             → exact phrase matching
project:"my-app" "database"    → filter by project

Enabling Vector Search

Vector search provides semantic similarity matching (finding related concepts even without exact keywords). It requires Ollama with an embedding model.

Quick Setup

Ask Claude to set it up for you:

"Set up Ollama for vector search"

Or manually:

# Install Ollama (macOS)
brew install ollama

# Start Ollama service
brew services start ollama

# Pull the embedding model
ollama pull nomic-embed-text

Then generate embeddings:

"Rebuild the history index with embeddings"

How I

... View full README on GitHub