claude-code-history-mcp/README.md

MCP server for Claude Code conversation history tracking and analysis

# 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:**
```json
{
  "startDate": "2025-06-30",
  "limit": 50,
  "messageTypes": ["user"],
  "timezone": "Asia/Tokyo"
}
```

**Response includes pagination info:**
```json
{
  "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

```bash
# 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):

```json
{
  "mcpServers": {
    "claude-code-history": {
      "command": "npx",
      "args": ["claude-code-history-mcp"]
    }
  }
}
```

Alternatively, if you have installed the package globally:

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

## Recommended Workflow 🚀

### 1. **Explore Available Data**
```json
// Start with list_projects to see what's available
{"tool": "list_projects"}
```

### 2. **Find Relevant Sessions**
```json
// 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**
```json
// 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:**
```json
{
  "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