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