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

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

Requirements

• Python 3.10+
• Claude Code (for MCP integration)
• Modern web browser (for GUI)

Contributing

Issues and pull requests are welcome at github.com/es6kr/claude-session-manager-mcp

License

MIT