How do I use claude-session-manager?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-session-manager list my recent sessions in the webapp project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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

Install Server

A

security – no known vulnerabilities

F

license - not found

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

claude-session-manager