Claude Code History

You can use Claude Code History MCP Server to access, filter, and search through Claude Code conversation history. It provides fast, paginated access to your data with smart filtering by message type and timezone-aware date handling, helping you explore projects, sessions, and specific content efficiently.

How to use

You interact with the server through an MCP client. Start by listing available projects to understand what data exists, then drill into sessions for a project and time range, retrieve targeted history with pagination, and finally search across conversations for relevant content.

Practical usage patterns you can follow:

• Discover all Claude Code conversation data with list_projects to get project paths and activity.
• Narrow down to a specific project with list_sessions, optionally filtering by startDate, endDate, and timezone to focus your exploration.
• Retrieve detailed conversation history for a session with get_conversation_history, using pagination (limit and offset) and filtering to show only user messages by default for efficiency.
• Find relevant context quickly with search_conversations by keywords, across projects and date ranges, then pull detailed history as needed.

How to install

Prerequisites: you need Node.js and npm installed on your system.

Install the MCP server CLI locally or run it directly with npx.

# Run without a local install
npx claude-code-history-mcp

# Install globally for easy reuse
npm install -g claude-code-history-mcp

Configuration and usage with MCP clients

Configure your MCP client to connect to the Claude Code History MCP server. You can either invoke the server via npx for each session or run it globally and reference the binary directly.

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

If you have installed the package globally, you can reference the executable directly in your MCP client configuration.

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

Notes on usage and workflow

Use list_projects first to understand what data is available, then list_sessions to locate relevant sessions. Retrieve targeted history with get_conversation_history using sensible defaults (limit to avoid large payloads) and enable timezone-aware filtering. When searching for topics, use search_conversations with a keyword query and apply date ranges to narrow results, followed by get_conversation_history to inspect the context.

Security and data handling

The MCP server accesses data locally from your Claude Code history files stored under your user directory. Ensure you control access to your machine and MCP client configurations to prevent exposure of sensitive data.

Troubleshooting

If you encounter connectivity issues, verify that you can run claude-code-history-mcp via npx or your global installation. Check that your MCP client is configured with the correct server name and the command/arguments shown in your client configuration.

Tools and capabilities overview

The server provides four primary tools to explore Claude Code history: list_projects, list_sessions, get_conversation_history, and search_conversations. Each tool focuses on a specific data access pattern—overview, session discovery, detailed history with pagination, and keyword-driven search.

Available tools

list_projects

Discover all projects with Claude Code conversation history, returning project paths, session counts, message counts, and last activity time.

list_sessions

List conversation sessions for exploration and filtering by project path, date range, and timezone; returns session IDs, timestamps, message counts, and project paths.

get_conversation_history

Retrieve paginated conversation history with smart filtering by message types, timezone, and date; supports limit, offset, and timezone-aware date normalization.

search_conversations

Search across all conversation content by keywords with filtering by project, date range, and timezone to locate relevant sessions.