# 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

```bash
# 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:

```bash
claude mcp add claude-session-manager -- uvx claude-session-manager-mcp
```

Or manually edit `~/.claude.json`:

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

### Web GUI

Launch the web interface:

```bash
# 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

```bash
# 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

```bash
# 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](https://github.com/es6kr/claude-session-manager-mcp)

## License

MIT