claude-session-manager-mcp

MCP server for managing Claude Code conversation sessions with GUI support.

Manage your Claude Code conversation history (~/.claude/projects) through MCP tools or a web-based GUI interface.

Features

📋 Session Management: List, rename, and delete conversation sessions
🗑️ Smart Cleanup: Automatically identify and clean empty or invalid sessions
🌐 Web GUI: Beautiful web interface for browsing conversation history
🔧 MCP Integration: Full MCP protocol support for Claude Code
🚀 Easy Install: One-line installation with uvx

Install

# Using uvx (recommended) uvx claude-session-manager-mcp # Or install globally uv tool install claude-session-manager-mcp # Web GUI uvx --from claude-session-manager-mcp claude-session-manager-web

Usage

Claude Code MCP Integration

Add to Claude Code:

claude mcp add claude-session-manager -- uvx claude-session-manager-mcp

Or manually edit ~/.claude.json:

{ "mcpServers": { "claude-session-manager": { "command": "uvx", "args": ["claude-session-manager-mcp"] } } }

Web GUI

Launch the web interface:

# Direct launch uvx --from claude-session-manager-mcp claude-session-manager-web # Or via MCP tool (from Claude Code) > Use the start_gui tool to launch web interface

The GUI will open at http://localhost:5050 with features:

Browse all projects and sessions
Search conversations
View full conversation history
Rename sessions with inline editing
Delete unwanted sessions
Bulk cleanup of empty sessions

MCP Tools

Tool	Description
`list_projects`	List all Claude Code projects with session counts
`list_sessions`	List all sessions in a specific project
`rename_session`	Add descriptive title prefix to session
`delete_session`	Delete session (safely backed up to .bak)
`preview_cleanup`	Preview sessions that can be cleaned
`clear_sessions`	Delete empty and invalid API key sessions
`start_gui`	Launch web GUI and open in browser
`stop_gui`	Stop the web GUI server

Examples

Via Claude Code

List all projects: > @claude-session-manager list_projects List sessions in a project: > @claude-session-manager list_sessions project_name="-Users-young-works-myproject" Rename a session: > @claude-session-manager rename_session project_name="..." session_id="abc123" new_title="Fix authentication bug" Launch web GUI: > @claude-session-manager start_gui

Via CLI

# Run MCP server (stdio mode) uvx claude-session-manager-mcp # Launch web GUI uvx --from claude-session-manager-mcp claude-session-manager-web

Project Structure

~/.claude/projects/ ├── -Users-young-works-project1/ │ ├── session1.jsonl │ ├── session2.jsonl │ └── agent-xxx.jsonl ├── -Users-young-works-project2/ └── .bak/ # Deleted sessions backup └── project_session.jsonl

Development

# Clone repository git clone https://github.com/es6kr/claude-session-manager-mcp.git cd claude-session-manager-mcp # Install dependencies uv sync # Run MCP server locally uv run claude-session-manager-mcp # Run web GUI locally uv run claude-session-manager-web # Run from project directory (development mode) uv run --directory /path/to/claude-session-manager-mcp claude-session-manager-mcp

How It Works

Session Detection: Scans ~/.claude/projects/ for .jsonl files
Smart Parsing: Extracts titles from first user message, removing IDE context tags
Safe Deletion: Moves deleted sessions to .bak folder for recovery
Cleanup Logic: Identifies empty sessions and invalid API key errors
Web Server: Flask-based GUI with RESTful API