mcp-sessions

Search and browse Claude Code conversation history across all your projects.

Русская версия

Features

• Cross-project search — search sessions in any project, not just the current one

• Smart project resolution — use short names (myapp), full paths, or * for all projects

• Full-text search — AND-matching across sessions with snippet context

• Git integration — see commits made during a session

• System tag filtering — strips Claude Code internal tags from displayed content

Tools

Install

git clone https://github.com/yurich-ru/mcp-sessions.git
cd mcp-sessions
chmod +x setup.sh
./setup.sh

The setup script will print the JSON config to add to your ~/.claude.json.

Manual setup

python3 -m venv venv
./venv/bin/pip install -r requirements.txt

Add to ~/.claude.json:

{
  "mcpServers": {
    "sessions": {
      "type": "stdio",
      "command": "/path/to/mcp-sessions/venv/bin/python",
      "args": ["/path/to/mcp-sessions/server.py"]
    }
  }
}

Restart Claude Code.

Usage examples

From Claude Code, the tools are available automatically:

• "Show my recent sessions" → sessions_list

• "Search our conversations about auth" → sessions_search(query="auth")

• "Find discussions about auth in project backend" → sessions_search(query="auth", project="backend")

• "Search all projects for deploy issues" → sessions_search(query="deploy", project="*")

• "What projects have session history?" → sessions_projects

Environment variables

How it works

Claude Code stores conversation history as JSONL files in ~/.claude/projects/<project-name>/. Each project directory name is derived from the filesystem path (e.g., /home/user/myapp → -home-user-myapp).

This server reads those files and provides search/browse tools via the MCP protocol.

Requirements

• Python 3.10+

• mcp package (installed automatically)

• Claude Code (session files must exist in ~/.claude/projects/)