The claude-sessions-mcp server manages Claude Code project sessions and chat history through MCP tools and a web interface.
Core Features:
Project Management: List all Claude Code projects with session counts
Session Operations: List, rename (via title prefixes), and delete sessions (safely moved to .bak folder for recovery)
Message Management: Delete individual messages with automatic UUID chain repair
Cleanup Operations: Preview and execute bulk cleanup to remove empty sessions, invalid API key sessions, and orphaned agent files
File Tracking: Get lists of files changed in sessions and view diff summaries with snapshot information
Web Interface: Start/stop a SvelteKit-based GUI (default port 5173) with auto-open browser, providing visual management of projects, sessions, conversation history, inline editing, and bulk cleanup operations
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-sessions-mcplist my recent Claude Code sessions"
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-sessions-mcp
⚠️ DEPRECATED: This package has been replaced by claude-code-sessions.
Please migrate to the new package:
npm uninstall claude-sessions-mcp npm install claude-code-sessions
MCP (Model Context Protocol) server and Web UI for managing Claude Code sessions.
Features
Project Listing: Browse Claude Code project folders
Session Management: List, rename, and delete sessions
Message Management: View and delete messages within sessions
Cleanup: Clear empty sessions and remove invalid API key messages
Web UI: SvelteKit-based web interface
Installation
# Using npx (recommended)
npx claude-sessions-mcp
# Or install globally
npm install -g claude-sessions-mcpUsage
Claude Code MCP Integration
Add to Claude Code:
claude mcp add claude-sessions -- npx claude-sessions-mcpOr manually edit ~/.claude.json:
{
"mcpServers": {
"claude-sessions": {
"command": "npx",
"args": ["claude-sessions-mcp"]
}
}
}Web GUI
Launch the web interface via MCP tool (from Claude Code):
> Use the start_gui tool to launch web interfaceThe GUI opens at http://localhost:5050 with features:
Browse all projects and sessions
View full conversation history
Rename sessions with inline editing
Delete unwanted sessions
Bulk cleanup of empty sessions
Development
# Enable corepack
corepack enable
# Install dependencies
pnpm install
# Start web development server
pnpm dev
# MCP server development mode
pnpm dev:mcpBuild
pnpm buildMCP Server Tools
Available Tools
Tool | Description |
| List Claude Code projects |
| List sessions in a project |
| Rename a session |
| Delete a session (moves to backup folder) |
| Delete a message and repair UUID chain |
| Preview sessions to be cleaned |
| Clear empty sessions and invalid messages |
| Start the web UI |
| Stop the web UI |
Tech Stack
MCP Server: Node.js + TypeScript + Effect
Web UI: SvelteKit + Svelte 5
Build: tsup (MCP), Vite (Web)
Package Manager: pnpm (corepack)
Effect-TS Patterns
This project uses Effect for functional async operations:
import { Effect, pipe, Array as A, Option as O } from 'effect'
// Define an Effect (lazy, composable)
const listProjects = Effect.gen(function* () {
const files = yield* Effect.tryPromise(() => fs.readdir(dir))
return files.filter((f) => f.endsWith('.jsonl'))
})
// Parallel execution with concurrency control
const results =
yield *
Effect.all(
items.map((item) => processItem(item)),
{ concurrency: 10 }
)
// Option for nullable values
const title = pipe(
messages,
A.findFirst((m) => m.type === 'user'),
O.map((m) => extractTitle(m)),
O.getOrElse(() => 'Untitled')
)
// Run in SvelteKit endpoint
export const GET = async () => {
const result = await Effect.runPromise(listProjects)
return json(result)
}License
MIT