{
  "markdown": "# Cowork History MCP\n\n<!-- mcp-name: io.github.egoughnour/cowork-history -->\n\nAn MCP (Model Context Protocol) server for searching and browsing your Claude conversation history stored in `~/.claude/`. Works with both Claude Code and Cowork conversations.\n\n## Features\n\n- **Hybrid Search** - Combines multiple search methods for best results:\n  - **SQLite FTS5** - Fast full-text search with BM25 ranking\n  - **macOS Spotlight** - Leverages system content indexing via `mdfind`\n  - **Vector Embeddings** - Semantic similarity search (optional, requires Ollama)\n- **Smart Path Reconstruction** - Recovers actual filesystem paths via probing (not heuristic guessing)\n- **Persistent Index** - SQLite database with incremental updates for fast queries\n- **Ollama Setup Tools** - Automated installation and configuration for embeddings\n\n## Installation\n\n### Option 1: Claude Desktop (One-Click Install)\n\nDownload `cowork-history.mcpb` from the [latest release](https://github.com/egoughnour/cowork-history/releases/latest) and double-click to install.\n\n### Option 2: Via uvx (Recommended for CLI)\n\n```bash\nuvx cowork-history\n```\n\n### Option 3: Via pip\n\n```bash\npip install cowork-history\n```\n\n### Option 4: Manual Configuration\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"cowork-history\": {\n      \"command\": \"uvx\",\n      \"args\": [\"cowork-history\"],\n      \"env\": {\n        \"OLLAMA_URL\": \"http://localhost:11434\",\n        \"EMBEDDING_MODEL\": \"nomic-embed-text\"\n      }\n    }\n  }\n}\n```\n\n## Quick Start\n\nOnce installed, Claude can search your conversation history:\n\n```\n\"What did we discuss about authentication last week?\"\n\"Find the conversation where we debugged the payment webhook\"\n\"Show me my conversations in the my-project folder\"\n```\n\n## Available Tools\n\n### Search & Browse\n\n| Tool | Description |\n|------|-------------|\n| `cowork_history_search` | Search conversations using hybrid search (FTS + Spotlight + vector) |\n| `cowork_history_list` | List recent conversations, optionally filtered by project |\n| `cowork_history_get` | Get full content of a specific conversation by session ID |\n| `cowork_history_projects` | List all projects with conversation history |\n| `cowork_history_stats` | Get statistics and search capability status |\n| `cowork_history_reindex` | Rebuild index and optionally generate embeddings |\n\n### Ollama Setup (for Vector Search)\n\n| Tool | Description |\n|------|-------------|\n| `history_system_check` | Check system requirements for Ollama |\n| `history_setup_ollama` | Install Ollama via Homebrew (macOS) |\n| `history_setup_ollama_direct` | Install Ollama via direct download (no Homebrew) |\n| `history_ollama_status` | Check Ollama status and embedding model availability |\n\n## Search Modes\n\nThe `cowork_history_search` tool supports multiple search modes:\n\n| Mode | Description |\n|------|-------------|\n| `auto` (default) | Uses all available methods, best results |\n| `fts` | Full-text search only (fastest) |\n| `spotlight` | macOS Spotlight only |\n| `vector` | Semantic similarity only (requires Ollama) |\n| `hybrid` | Explicit combination with ranking |\n\n### Search Examples\n\n```\n\"authentication bug\"           → finds conversations with both words\n\"how to deploy\"                → semantic search finds related discussions\n\"\\\"exact phrase\\\"\"             → exact phrase matching\nproject:\"my-app\" \"database\"    → filter by project\n```\n\n## Enabling Vector Search\n\nVector search provides semantic similarity matching (finding related concepts even without exact keywords). It requires Ollama with an embedding model.\n\n### Quick Setup\n\nAsk Claude to set it up for you:\n```\n\"Set up Ollama for vector search\"\n```\n\nOr manually:\n\n```bash\n# Install Ollama (macOS)\nbrew install ollama\n\n# Start Ollama service\nbrew services start ollama\n\n# Pull the embedding model\nollama pull nomic-embed-text\n```\n\nThen generate embeddings:\n```\n\"Rebuild the history index with embeddings\"\n```\n\n## How It Works\n\n### Indexing\n\nThe server maintains a SQLite database at `~/.claude/.history-index/conversations.db` with:\n- FTS5 virtual table for fast full-text search\n- Conversation metadata (session ID, project, timestamps, topic)\n- Full content for comprehensive search\n- Path cache for reconstructed paths\n- Embeddings table for vector search (optional)\n\nThe index updates automatically when you search (if >5 minutes old) or you can force a rebuild with `cowork_history_reindex`.\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL |\n| `EMBEDDING_MODEL` | `nomic-embed-text` | Ollama embedding model |\n\n## Troubleshooting\n\n### No conversations found\n\n1. Make sure `~/.claude/` directory exists\n2. Check that you have conversation history (use Claude Code or Cowork first)\n3. Verify the MCP server is properly configured\n\n### Vector search not available\n\n1. Check Ollama is installed: `ollama --version`\n2. Check Ollama is running: `curl http://localhost:11434/api/tags`\n3. Check model is available: `ollama list`\n4. Pull embedding model: `ollama pull nomic-embed-text`\n\n### Search not finding expected results\n\n- Try natural language queries (semantic search is more flexible)\n- Use `mode: \"fts\"` for exact phrase matching\n- Check `cowork_history_stats` to see which search backends are active\n\n## Development\n\n### Running locally\n\n```bash\n# Clone the repository\ngit clone https://github.com/egoughnour/cowork-history\ncd cowork-history\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest tests/\n\n# Run the server directly\npython -m src.cowork_history_server\n```\n\n### Testing with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector uvx cowork-history\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n",
  "bytes": 5852,
  "sha": "c65fe227cfc4a077c032fe235d05d1b960f15f3d744faa4473c4e4f6e66a779c",
  "repo_slug": "egoughnour/cowork-history",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_egoughnour_cowork_history_47cfd1c4/readme"
}