How do I use Claude Code History MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Claude Code History MCP Server search my recent sessions for 'OAuth implementation'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Claude Code History MCP Server

by yudppp

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

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

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?

list_projects → See active projects
get_conversation_history with today's date and messageTypes: ["user"]

Project Deep Dive

Analyze my recent work on Project X

list_sessions with specific project path
get_conversation_history for relevant sessions
Use pagination to browse through all data

Topic Research

Find all conversations about "API integration" in a specific project

search_conversations with query "API integration", projectPath, and date range
Use results to identify relevant sessions
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)

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of conversations to return (default: 20)
`offset`	No	Number of conversations to skip for pagination (default: 0)
`endDate`	No	End date in ISO format (optional)
`timezone`	No	Timezone for date filtering (e.g., "Asia/Tokyo", "UTC"). Defaults to system timezone.
`sessionId`	No	Specific session ID to get history for (optional)
`startDate`	No	Start date in ISO format (optional)
`messageTypes`	No	Filter by specific message types. Defaults to ["user"] to reduce data volume. Use ["user", "assistant"] to include Claude responses.

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions 'paginated' and 'targeted data,' but it does not reveal key behaviors like the default messageTypes filter (['user']) to reduce data volume, or whether the operation is read-only. It also fails to mention pagination limits or response format, which are important for an API with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that immediately states the action and then provides usage context in parentheses. Every word earns its place, with no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 7 parameters, no output schema, and no annotations, the description should provide more context about expected return values and important behaviors. It omits any mention of response structure, default message filtering, or how to use parameters together. The description is too brief to be considered complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter meaning beyond the schema, only hinting at 'targeted data' which suggests filtering capabilities. It does not elaborate on how parameters interact (e.g., startDate/endDate requiring timezone), but the schema definitions already provide clear descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb and resource: 'Get paginated conversation history.' It also distinguishes itself from sibling tools by positioning it as a follow-up to list_projects/list_sessions for targeted data retrieval, making it unique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly guides when to use this tool: 'use after exploring with list_projects/list_sessions for targeted data.' This provides clear context and implies that list_projects/list_sessions are for broader exploration. However, it does not explicitly mention when not to use it or compare with search_conversations, so it lacks full exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsA

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It reveals that the tool filters to only projects with conversation history, which is useful. However, it does not describe output format, ordering, pagination, or potential limitations, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core action and resource. It includes a helpful usage hint without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's minimal complexity (no parameters, no annotations, no output schema), the description sufficiently conveys its purpose and basic return scope. It lacks explicit return-field details but remains adequate for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema provides complete coverage of an empty set. The description does not need to explain parameters, but the baseline of 4 for no-parameter tools is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'List all projects with Claude Code conversation history', using a specific verb and resource. It distinguishes itself from siblings like list_sessions (lists sessions) and search_conversations (searches conversations) by focusing on projects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'start here to explore available data' provides clear guidance on when to use this tool as an entry point. It suggests usage context but does not explicitly mention alternatives or exclusions, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sessionsA

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

ParametersJSON Schema

Name	Required	Description
`endDate`	No	End date in ISO format (optional)
`timezone`	No	Timezone for date filtering (e.g., "Asia/Tokyo", "UTC"). Defaults to system timezone.
`startDate`	No	Start date in ISO format (optional)
`projectPath`	No	Filter by specific project path (optional)

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It offers no extra behavioral details such as default behavior when no filters are supplied, result ordering, pagination, or access limits. It essentially restates the tool's basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 12 words, efficiently combining purpose and a usage hint. Every word contributes value, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 optional parameters and no output schema, the description covers purpose and workflow but omits default behavior and return format. It is serviceable but leaves some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description's 'project or date range' phrasing loosely maps to the parameters but adds no additional meaning beyond the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action ('List') and resource ('conversation sessions') with scope ('for a project or date range'). It is unambiguous, though it does not explicitly distinguish from sibling tools like search_conversations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit workflow guidance ('use after list_projects to find specific sessions'), which is helpful context. However, it does not mention alternatives or when not to use this tool, so it lacks exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_conversationsA

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

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of results to return (default: 30)
`query`	Yes	Search query to find in conversation content
`endDate`	No	End date in ISO format (optional)
`timezone`	No	Timezone for date filtering (e.g., "Asia/Tokyo", "UTC"). Defaults to system timezone.
`startDate`	No	Start date in ISO format (optional)
`projectPath`	No	Filter by specific project path (optional)

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for disclosing behavioral traits. It merely restates the action without mentioning read-only nature, return format, sorting, or potential side effects. This offers essentially no guidance beyond the tool's purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler words. It efficiently communicates the core purpose and a usage context, earning a perfect score for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with six parameters and no output schema, the description omits crucial details such as result format, query matching behavior, date range semantics, and potential limitations. Without annotations, this minimal description is incomplete for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are well-documented in the input schema. The description adds no additional parameter-specific context, leaving it at the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('Search') and resource ('conversation history'), and the parenthetical ('useful for finding specific topics across all conversations') clarifies its scope and differentiates it from sibling tools like get_conversation_history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool ('useful for finding specific topics across all conversations') but does not explicitly mention alternatives or exclusions. Since siblings exist, an explicit when-not-to-use would elevate it to a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

4 tool updatesv1.1.1Aug 14, 2026
- First observedget_conversation_history
- First observedlist_projects
- First observedlist_sessions
- First observedsearch_conversations

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-08-14 03:20 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 issues

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp
dev.augments
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Developer Tools Documentation Access
2128
LLMemoryOAuth
io.github.meir-may
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Search Knowledge & Memory
2
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
mcpOAuth
com.bullpenstrategygroup.rotunda
An MCP server that provides congressional transcripts
Government Data Search Open Data
2

Related MCP Servers

Claude Historian
Developer Tools Code Execution Knowledge & Memory
Vvkmnn
A
license
B
quality
D
maintenance
MCP server that lets you search your Claude Code conversation history to find past solutions, track file changes, and learn from previous work.
Updated 3 months ago (2026-06-15 09:09 UTC)
8
157 npm
178
MIT
ClaudeHistoryMCP
Knowledge & Memory Search Developer Tools
jhammant
A
license
A
quality
D
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.
Updated 7 months ago (2026-02-27 17:15 UTC)
9
6 npm
66
MIT
cc-session-search
Developer Tools Search
bwads001
F
license
B
quality
D
maintenance
An MCP server that provides tools for searching and analyzing Claude Code conversation history.
Updated a year ago (2025-09-20 23:15 UTC)
8
4
-
engram-mcp
Search Knowledge & Memory
lowbridgee
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.
Updated 6 months ago (2026-03-26 15:33 UTC)
10 npm
MIT

Claude Code History MCP Server

Features

1. list_projects 👀 Start Here

2. list_sessions 📁 Explore Sessions

3. get_conversation_history 💬 Get Detailed Data

4. search_conversations 🔍 Find Specific Content

Quick Start

Usage with MCP Clients

Recommended Workflow 🚀

1. Explore Available Data

2. Find Relevant Sessions

3. Get Targeted Data

Data Source

Smart Features 💡

Message Type Filtering

Timezone Intelligence

Pagination Support

Use Cases

Daily Work Review

Project Deep Dive

Topic Research

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

1. `list_projects` 👀 Start Here

2. `list_sessions` 📁 Explore Sessions

3. `get_conversation_history` 💬 Get Detailed Data

4. `search_conversations` 🔍 Find Specific Content