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:

Response includes pagination info:

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

Usage with MCP Clients

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

Alternatively, if you have installed the package globally:

Recommended Workflow 🚀

1. Explore Available Data

2. Find Relevant Sessions

3. Get Targeted Data

Data Source

This server reads Claude Code history files (.jsonl format) stored in ~/.claude/projects/.

Smart Features 💡

Message Type Filtering

• Default: Only ["user"] messages to reduce data volume

• Full conversation: Use ["user", "assistant"]

• Everything: Use ["user", "assistant", "system", "result"]

Timezone Intelligence

• Automatically detects your system timezone

• Supports explicit timezone specification (e.g., "Asia/Tokyo")

• Smart date normalization (e.g., "2025-06-30" → proper timezone bounds)

Pagination Support

• Efficient handling of large datasets

• total_count helps you understand data volume

• has_more indicates if there's additional data

Use Cases

Daily Work Review

1. list_projects → See active projects

2. get_conversation_history with today's date and messageTypes: ["user"]

Project Deep Dive

1. list_sessions with specific project path

2. get_conversation_history for relevant sessions

3. Use pagination to browse through all data

Topic Research

1. search_conversations with query "API integration", projectPath, and date range

2. Use results to identify relevant sessions

3. get_conversation_history for detailed context

Example with advanced filtering:

License

MIT