claude-session-mcp

Fork-aware MCP server for searching and navigating Claude Code session history.

Why fork-aware?

Claude Code stores session history as JSONL files in ~/.claude/projects/. These files are trees, not linear logs. Each record has a uuid and parentUuid — when a user retries or edits a prompt, two records share the same parent, creating a fork. Most tools ignore this and treat sessions as flat logs, giving incorrect results.

This server correctly parses the tree structure, detects forks, identifies primary vs abandoned branches, and stitches compaction boundaries back together.

Installation

Requires uv (available via most package managers, e.g. pacman -S uv on Arch/CachyOS, brew install uv on macOS).

Install from GitHub

uv tool install git+https://github.com/Gunther-Schulz/claude-session-mcp

This creates an isolated environment and puts claude-session-mcp on your PATH. Update with:

uv tool upgrade claude-session-mcp

Alternative: run without installing

uvx --from git+https://github.com/Gunther-Schulz/claude-session-mcp claude-session-mcp

This resolves dependencies on each launch (slower startup, but no install step).

Configuration

Add to ~/.claude/.mcp.json (global) or .mcp.json in your project root (per-project):

{
  "mcpServers": {
    "session-search": {
      "command": "claude-session-mcp"
    }
  }
}

If claude-session-mcp is not on your PATH (e.g. ~/.local/bin isn't in the base PATH), use the full path instead:

{
  "mcpServers": {
    "session-search": {
      "command": "/home/your-user/.local/bin/claude-session-mcp"
    }
  }
}

Then use the tools from within Claude Code conversations.

Tools

list_projects

List all Claude Code projects with session counts and sizes.

list_sessions

List sessions for a project (or all projects), sorted by most recent first. Shows record count, date range, and subagent count. Supports pagination.

Params: project, limit, offset

search

Full-text search across session history. Returns matches with 2 ancestor messages for conversational context, and indicates whether each match is on the primary branch or an abandoned fork.

Params: query, project, max_results, include_subagents

get_tree

Get the conversation tree structure for a session: fork points, branch summaries, compaction boundaries, and leaf nodes. Use this to understand session structure before navigating.

Params: session_id, project

get_thread

Get a specific conversation thread (root-to-leaf path). Filters to user/assistant messages only. Supports pagination for long threads. Empty leaf_uuid returns the primary thread.

Params: session_id, leaf_uuid, project, offset, limit, include_tool_calls

get_forks

Get fork point details with diverging branches. Shows which branch the user continued with (primary) vs abandoned, with descendant counts and preview text.

Params: session_id, project, fork_uuid

How it works

• Tree parsing: Builds uuid → Record and parentUuid → [child UUIDs] indexes from JSONL
• Compact boundary stitching: System records with logicalParentUuid are stitched back into the tree, reconnecting compacted conversations
• Fork detection: A parent with 2+ meaningful children (user/assistant type) is a fork point
• Primary branch: At each fork, the child with the latest timestamp is the user's final choice
• Lazy loading: Session files are only parsed when a tool needs the data
• Lightweight metadata: list_sessions avoids full JSON parsing for speed

Acknowledgements

The core insight that Claude Code session files are trees (not linear logs) comes from claude-session-tools by aurora-thesean. That project's clear documentation of the parentUuid tree structure and fork semantics informed the design of this MCP server. Our implementation adds compact boundary stitching, primary branch detection, lazy loading, and the MCP interface, but the foundational understanding of the data model originated there.

License

MIT