Claude Code History MCP Server

An MCP server for retrieving and analyzing Claude Code conversation history with smart filtering and pagination.

Features

This MCP server provides 4 powerful tools for exploring your Claude Code conversation history:

1. list_projects 👀 Start Here

Discover all projects with Claude Code conversation history.

Why use this first: Get an overview of all available data before diving deeper.

Returns: Project paths, session counts, message counts, and last activity time.

2. list_sessions 📁 Explore Sessions

List conversation sessions for exploration and filtering.

Parameters:

• projectPath (optional): Filter by specific project
• startDate (optional): Start date (e.g., “2025-06-30”)
• endDate (optional): End date (e.g., “2025-06-30”)
• timezone (optional): Timezone for date filtering (e.g., “Asia/Tokyo”, “UTC”)

Returns: Session IDs, timestamps, message counts, and project paths.

3. get_conversation_history 💬 Get Detailed Data

Retrieve paginated conversation history with smart filtering.

Key Features:

• Pagination: limit (default: 20) and offset for efficient data handling
• Message Filtering: messageTypes defaults to ["user"] to reduce data volume
• Timezone Support: Automatic timezone detection or specify (e.g., “Asia/Tokyo”)
• Date Filtering: Smart date normalization with timezone awareness

Parameters:

• sessionId (optional): Specific session ID
• startDate (optional): Start date (e.g., “2025-06-30”)
• endDate (optional): End date (e.g., “2025-06-30”)
• limit (optional): Max entries per page (default: 20)
• offset (optional): Skip entries for pagination (default: 0)
• messageTypes (optional): ["user"] (default), ["user", "assistant"], etc.
• timezone (optional): e.g., “Asia/Tokyo”, “UTC” (auto-detected)

Example:

{
  "startDate": "2025-06-30",
  "limit": 50,
  "messageTypes": ["user"],
  "timezone": "Asia/Tokyo"
}

Response includes pagination info:

{
  "entries": [...],
  "pagination": {
    "total_count": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

4. search_conversations 🔍 Find Specific Content

Search across all conversation content by keywords with advanced filtering.

Parameters:

• query (required): Search terms
• limit (optional): Max results (default: 30)
• projectPath (optional): Filter by specific project path
• startDate (optional): Start date (e.g., “2025-06-30”)
• endDate (optional): End date (e.g., “2025-06-30”)
• timezone (optional): Timezone for date filtering (e.g., “Asia/Tokyo”, “UTC”)

Quick Start

# Install directly via npx (no local installation needed)
npx claude-code-history-mcp

# Or install globally
npm install -g claude-code-history-mcp

Usage with MCP Clients

Add the following configuration to your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {