Cowork History

You can run this MCP server to search and browse your Claude conversation history stored in your Home directory. It combines fast text search, system indexing, and optional semantic search to help you find, filter, and inspect your past conversations across Claude Code and Cowork.

How to use

You interact with the cowork-history MCP through a client that supports MCP servers. Start the server using the method you chose, then connect your Claude Desktop client or other MCP-compatible frontend to the cowork-history server. You can perform full-text searches, browse recent conversations, filter results by project, and fetch full conversation content. You can also rebuild the index or enable vector search for semantic matching when you have embedding support set up.

How to install

Prerequisites: ensure you have a modern Python environment for the server and a supported method for running the MCP client. You have three installation options.

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). Run the command below to install and run the MCP server via uvx.

uvx cowork-history

Option 3: Via Python package index. Install the package with pip.

pip install cowork-history

Option 4: Manual configuration for Claude Desktop. Add the following MCP server entry to your Claude Desktop configuration file at ~/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"
      }
    }
  }
}

Environment variables

Two environment variables are used by the standard runtime configuration. You can override these values if needed.

• OLLAMA_URL: URL of the Ollama server. Default: http://localhost:11434.

• EMBEDDING_MODEL: Name of the embedding model used for vector search. Default: nomic-embed-text.

Additional setup for vector search

If you want semantic similarity search, install and run Ollama, then pull an embedding model and generate embeddings for your index.

Quick setup example (vector search): you can prompt Claude to help set up Ollama, or perform the steps manually.

# Install Ollama (macOS)
brew install ollama

# Start Ollama service
brew services start ollama

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

Troubleshooting

If you encounter issues, verify the history directory exists, ensure you have conversations stored, and confirm the MCP server is configured correctly.

Vector search issues usually relate to Ollama status or embedding model availability. Check Ollama is installed and running, verify the model is available, and re-pull the model if needed.

Available tools

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

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