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": {
    "claude-code-history": {
      "command": "npx",
      "args": ["claude-code-history-mcp"]
    }
  }
}

Alternatively, if you have installed the package globally:

{
  "mcpServers": {
    "claude-code-history": {
      "command": "claude-code-history-mcp"
    }
  }
}

Recommended Workflow 🚀

1. Explore Available Data

// Start with list_projects to see what's available
{"tool": "list_projects"}

2. Find Relevant Sessions

// List sessions for a specific project or date range with timezone
{
  "tool": "list_sessions",
  "projectPath": "/Users/yourname/code/my-project",
  "startDate": "2025-06-30",
  "timezone": "Asia/Tokyo"
}

3. Get Targeted Data

// Get conversation history with optimal settings
{
  "tool": "get_conversation_history", 
  "sessionId": "specific-session-id",
  "messageTypes": ["user"],  // Only your inputs (default)
  "limit": 50
}

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

What did I work on today?

1. list_projects → See active projects

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

Project Deep Dive

Analyze my recent work on Project X

1. list_sessions with specific project path

2. get_conversation_history for relevant sessions

3. Use pagination to browse through all data

Topic Research

Find all conversations about "API integration" in a specific project

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:

{
  "tool": "search_conversations",
  "query": "API integration",
  "projectPath": "/Users/yourname/code/my-project",
  "startDate": "2025-06-01",
  "endDate": "2025-06-30",
  "timezone": "Asia/Tokyo",
  "limit": 50
}

License

MIT