cowork-history
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cowork-history Find my conversation about debugging payment webhooks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
mdfindVector 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
Related MCP server: Memex
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-historyOption 3: Via pip
pip install cowork-historyOption 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 |
| Search conversations using hybrid search (FTS + Spotlight + vector) |
| List recent conversations, optionally filtered by project |
| Get full content of a specific conversation by session ID |
| List all projects with conversation history |
| Get statistics and search capability status |
| Rebuild index and optionally generate embeddings |
Ollama Setup (for Vector Search)
Tool | Description |
| Check system requirements for Ollama |
| Install Ollama via Homebrew (macOS) |
| Install Ollama via direct download (no Homebrew) |
| Check Ollama status and embedding model availability |
Search Modes
The cowork_history_search tool supports multiple search modes:
Mode | Description |
| Uses all available methods, best results |
| Full-text search only (fastest) |
| macOS Spotlight only |
| Semantic similarity only (requires Ollama) |
| 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 projectEnabling 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-textThen generate embeddings:
"Rebuild the history index with embeddings"How It Works
Indexing
The server maintains a SQLite database at ~/.claude/.history-index/conversations.db with:
FTS5 virtual table for fast full-text search
Conversation metadata (session ID, project, timestamps, topic)
Full content for comprehensive search
Path cache for reconstructed paths
Embeddings table for vector search (optional)
The index updates automatically when you search (if >5 minutes old) or you can force a rebuild with cowork_history_reindex.
Environment Variables
Variable | Default | Description |
|
| Ollama server URL |
|
| Ollama embedding model |
Troubleshooting
No conversations found
Make sure
~/.claude/directory existsCheck that you have conversation history (use Claude Code or Cowork first)
Verify the MCP server is properly configured
Vector search not available
Check Ollama is installed:
ollama --versionCheck Ollama is running:
curl http://localhost:11434/api/tagsCheck model is available:
ollama listPull embedding model:
ollama pull nomic-embed-text
Search not finding expected results
Try natural language queries (semantic search is more flexible)
Use
mode: "fts"for exact phrase matchingCheck
cowork_history_statsto see which search backends are active
Development
Running locally
# Clone the repository
git clone https://github.com/egoughnour/cowork-history
cd cowork-history
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest tests/
# Run the server directly
python -m src.cowork_history_serverTesting with MCP Inspector
npx @modelcontextprotocol/inspector uvx cowork-historyLicense
MIT License - see LICENSE file for details.
Available Tools
10 toolscowork_history_getGet Conversation DetailsARead-onlyIdempotent
Get full content of a specific conversation by session ID.
Inputs: params (required). Returns: result
cowork_history_listList Recent ConversationsARead-onlyIdempotent
List recent Claude conversations from the index, sorted by modification time.
Inputs: params (required). Returns: result
cowork_history_projectsList ProjectsBRead-onlyIdempotent
List all projects with conversation history, showing reconstructed paths.
Inputs: params (required). Returns: result
cowork_history_reindexRebuild IndexAIdempotent
Rebuild the conversation index and optionally generate embeddings.
Inputs: params (required). Returns: result
cowork_history_searchSearch ConversationsARead-onlyIdempotent
Search Claude conversation history using hybrid search.
Combines FTS5 full-text search, macOS Spotlight content indexing, and optional vector similarity (requires Ollama). Supports natural language, keywords, and "exact phrases".
Examples:
"authentication bug" - finds conversations mentioning both words
"how to deploy" - semantic search finds related discussions
project:"my-app" query:"database" - filter by project
Inputs: params (required). Returns: result
cowork_history_statsGet StatisticsBRead-onlyIdempotent
Get statistics about conversation history and search capabilities.
Inputs: params (required). Returns: result
history_ollama_statusA
Check Ollama server status and available models.
Returns whether Ollama is running and if the embedding model is available. Use to check if semantic/vector search is available.
Inputs: force_refresh. Returns: object
history_setup_ollamaA
Install Ollama via Homebrew (macOS).
Requires Homebrew pre-installed. Uses 'brew install' and 'brew services'. PROS: Auto-updates, pre-built binaries, managed service. CONS: Requires Homebrew, may prompt for sudo on first install.
Inputs: model, install, pull_model, start_service. Returns: object
history_setup_ollama_directA
Install Ollama via direct download (macOS).
Downloads from ollama.com to ~/Applications. PROS: No Homebrew needed, no sudo required, fully headless. CONS: Manual PATH setup, no auto-updates.
Inputs: model, install, pull_model, start_service. Returns: object
history_system_checkA
Check if system meets requirements for Ollama embeddings.
Verifies: macOS, Apple Silicon (M1/M2/M3/M4), RAM, Homebrew. Use before attempting Ollama setup.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools are distinct, but history_setup_ollama_direct and history_setup_ollama overlap as two installation methods for the same software. history_system_check and history_ollama_status are also somewhat related, though they check different aspects. Descriptions help clarify, but some ambiguity remains.
Naming is inconsistent: tools use two different prefixes (history_ vs cowork_history_) and mix verb-first (setup_ollama, search) with noun-first (system_check, ollama_status) patterns. This makes the tool set feel disjointed and harder to predict.
10 tools is within a reasonable range, but four of them are dedicated to Ollama setup/status, which is an optional dependency. This makes the set slightly heavier than necessary, though each tool still serves a distinct purpose.
The core history tools cover search, list, get, projects, stats, and reindex, providing solid lifecycle coverage for querying and maintaining conversation history. Minor gaps exist, such as lack of delete or export functionality, but they are not critical for the primary use case.
Maintenance
Related MCP Connectors
Search your knowledge bases from any AI assistant using hybrid RAG.
Search and read your Laxis meeting transcripts, AI summaries, and participants from Claude.
Your versioned prompt library: search, read, save and version prompts from Claude Code.
Read-only search of your Sortio knowledge graph (files and entities) for Claude and ChatGPT.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables comprehensive search and analysis of Claude Code conversation history using full-text search, optional semantic vector search, and conversation management tools. Provides fast SQLite-based indexing with role-based filtering, project organization, and hybrid search capabilities combining keyword and semantic matching.-
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving Claude Code conversation history that would otherwise expire after 30 days. Supports full-text search, semantic search, and session management with automatic backup of all conversations.28MIT
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving Claude Code conversation history via hybrid semantic and keyword search, allowing the agent to access its own past interactions.142 PyPI5MIT
- AlicenseNot gradedqualityDmaintenanceEnables searching and browsing past Claude Code conversations directly from within an active Claude session, with full-text search and cost tracking.MIT