Claude Code History MCP Server

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