Back to Browse
Free
Server data from the Official MCP Registry
Hybrid search for Cowork history: FTS, Spotlight, and semantic vectors
About
Hybrid search for Cowork history: FTS, Spotlight, and semantic vectors
Security Report
4.3
Use Caution4.3High RiskValid MCP server (1 strong, 2 medium validity signals). 6 known CVEs in dependencies (1 critical, 3 high severity) Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (4/4 approved).
3 files analyzed · 7 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
URL for Ollama server (default: http://localhost:11434)
Environment variable: OLLAMA_URL
Ollama embedding model (default: nomic-embed-text)
Environment variable: EMBEDDING_MODEL
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-egoughnour-cowork-history": {
"env": {
"OLLAMA_URL": "your-ollama-url-here",
"EMBEDDING_MODEL": "your-embedding-model-here"
},
"args": [
"cowork-history"
],
"command": "uvx"
}
}
}Documentation
View on GitHubFrom the project's GitHub README.
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 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_URL | http://localhost:11434 | Ollama server URL |
EMBEDDING_MODEL | nomic-embed-text | Ollama embedding model |
Troubleshooting
No conversations found
- Make sure
~/.claude/directory exists - Check 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 --version - Check Ollama is running:
curl http://localhost:11434/api/tags - Check model is available:
ollama list - Pull 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 matching - Check
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_server
Testing with MCP Inspector
npx @modelcontextprotocol/inspector uvx cowork-history
License
MIT License - see LICENSE file for details.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Fetch
Freeby Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
80.0K
Stars
4
Installs
5.3
Security
No ratings yet
Local
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
137
Stars
517
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
72
Installs
10.0
Security
4.6
Local