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 projectstartDate(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) andoffsetfor efficient data handling - Message Filtering:
messageTypesdefaults 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 IDstartDate(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 termslimit(optional): Max results (default: 30)projectPath(optional): Filter by specific project pathstartDate(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_counthelps you understand data volumehas_moreindicates if there's additional data
Use Cases
Daily Work Review
What did I work on today?
list_projects→ See active projectsget_conversation_historywith today's date andmessageTypes: ["user"]
Project Deep Dive
Analyze my recent work on Project X
list_sessionswith specific project pathget_conversation_historyfor relevant sessions- Use pagination to browse through all data
Topic Research
Find all conversations about "API integration" in a specific project
search_conversationswith query "API integration", projectPath, and date range- Use results to identify relevant sessions
get_conversation_historyfor 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