Skip to main content
Glama
Claude Code History MCP Server

Claude Code History MCP Server

by yudppp

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")

Related MCP server: ClaudeHistoryMCP

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"
    }
  }
}

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

Available Tools

4 tools
get_conversation_historyA

Get paginated conversation history (use after exploring with list_projects/list_sessions for targeted data)

Inputs: limit, offset, endDate, timezone, +3 more.

list_projectsA

List all projects with Claude Code conversation history (start here to explore available data)

Inputs: no named parameters.

list_sessionsA

List conversation sessions for a project or date range (use after list_projects to find specific sessions)

Inputs: endDate, timezone, startDate, projectPath.

search_conversationsA

Search through conversation history by content (useful for finding specific topics across all conversations)

Inputs: query (required), limit, endDate, timezone, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing projects, listing sessions, retrieving conversation history, and searching across history. The descriptions even guide the agent on the proper exploration flow, eliminating any ambiguity.

    Naming Consistency5/5

    All tool names follow the same verb_noun pattern (list_projects, list_sessions, get_conversation_history, search_conversations), making the API predictable and easy to navigate.

    Tool Count5/5

    The server is scoped to browsing and searching Claude Code history, and four tools cover this purpose without being excessive or sparse. Each tool is essential and earns its place.

    Completeness5/5

    The tool surface provides a complete workflow for exploring conversation history: discover projects, list sessions, retrieve detailed history, and search for specific content. No obvious gaps for a read-only history viewer.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that makes Claude Code conversation history searchable and proactively useful by indexing past sessions with hybrid BM25+TF-IDF search, extracting decisions and solutions, and auto-injecting relevant project context at session start.
      9
      9 npm
      69
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables semantic and keyword search over Claude Code conversation history stored locally, using hybrid search, local embeddings, and time-decay scoring.
      12 npm
      MIT