@ebowwa/claude-code-history-mcp

MCP server for accessing Claude Code conversation history with useful context.

Features

• Recent Activity: Quick overview of what was asked and done across all projects
• Session Summaries: Deep dive into sessions with topics, files, commands, and outcome
• Enhanced Sessions: List sessions with previews, durations, and message counts
• Full History: Retrieve complete conversation history with flexible filtering
• Search: Full-text search across all conversations

Tools

get_recent_activity (Recommended Starting Point)

Get recent activity across all projects - shows what was asked, what was done, and when.

{
  "name": "get_recent_activity",
  "arguments": {
    "limit": 10,
    "includeSummaries": true
  }
}

Returns:

• Session ID and project name
• What was asked (first user message)
• What was done (summary)
• Time ago
• Message count

get_session_summary

Get a detailed summary of a specific session.

{
  "name": "get_session_summary",
  "arguments": {
    "sessionId": "abc123",
    "includeToolCalls": true
  }
}

Returns:

• Topics discussed
• Files involved
• Commands run
• Tools used
• Outcome (completed/with issues)

list_sessions

List sessions with useful context - previews, durations, message counts.

{
  "name": "list_sessions",
  "arguments": {
    "projectPath": "/path/to/project",
    "includePreviews": true
  }
}

get_current_session

Get active session with project name, message count, latest prompt, time ago.

list_session_directories

List session directories with previews and context instead of just UUIDs.

get_conversation_history

Full conversation history (use when you need complete details).

search_conversations

Full-text search across all conversations.

Installation

# Install globally
npm install -g @ebowwa/claude-code-history-mcp

# Or run directly
bunx @ebowwa/claude-code-history-mcp

MCP Configuration

{
  "mcpServers": {
    "claude-code-history": {
      "command": "claude-code-history-mcp",
      "description": "Claude Code conversation history with useful context"
    }
  }
}

Installation

# Install dependencies
bun install

# Build the package
bun run build

# Or install globally
bun link

Configuration

The server can be configured via environment variables, ideally managed through Doppler:

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | CLAUDE_DIR | Path to Claude Code directory | ~/.claude | | DOPPLER_PROJECT | Doppler project name (optional) | - | | DOPPLER_CONFIG | Doppler config name | dev | | DOPPLER_TOKEN | Doppler auth token | - |

Using Doppler

1. Install Doppler CLI:

   # macOS
   brew install dopplerlabs/tap/doppler
   
   # Linux
   curl -sSL https://dl.doppler.com/install.sh | sh

2. Configure your project:

   # Login to Doppler
   doppler login
   
   # Setup your project
   doppler setup
   
   # Set environment variables
   doppler secrets set CLAUDE_DIR /path/to/.claude

3. Run with Doppler:

   doppler run -- bun run start

Example .env (for local development)

CLAUDE_DIR=/Users/yourname/.claude
DOPPLER_PROJECT=claude-code-history
DOPPLER_CONFIG=dev

Usage

As an MCP Server

Add to your Claude Code MCP configuration (~/.claude/mcp.json or similar):

{
  "mcpServers": {
    "claude-code-history": {
      "command": "doppler",
      "args": [
        "run",
        "--",
        "bun",
        "/path/to/@mcp/claude-code-history/dist/index.js"
      ],
      "env": {
        "DOPPLER_PROJECT": "your-project-name",
        "DOPPLER_CONFIG": "dev"
      }
    }
  }
}

Available Tools

1. list_projects

List all Claude Code projects.

{
  "name": "list_projects",
  "arguments": {}
}

2. list_sessions

List sessions for a specific project or date range.

{
  "name": "list_sessions",
  "arguments": {
    "projectPath": "/path/to/project",
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "timezone": "UTC"
  }
}

3. get_conversation_history

Get paginated conversation history with flexible filtering.

{
  "name": "get_conversation_history",
  "arguments": {
    "sessionId": "session-id",
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "limit": 20,
    "offset": 0,
    "messageTypes": ["user", "assistant"],
    "timezone": "UTC"
  }
}

4. search_conversations

Search across all conversations.

{
  "name": "search_conversations",
  "arguments": {
    "query": "database migration",
    "limit": 30,
    "projectPath": "/path/to/project",
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "timezone": "UTC"
  }
}

5. get_config

Get current configuration (useful for debugging Doppler integration).

{
  "name": "get_config",
  "arguments": {}
}

Development

# Development with hot reload
bun run dev

# Type checking
bun run typecheck

# Build
bun run build

# Start built server
bun run start

Examples

Example 1: Find all conversations about "authentication"

# Search across all projects
search_conversations --query "authentication" --limit 10

Example 2: Get conversation history for a specific date range

# Get conversations from January 2024
get_conversation_history --startDate "2024-01-01" --endDate "2024-01-31"

Example 3: List sessions for a project

# List all sessions for a specific project
list_sessions --projectPath "/path/to/project"

Example 4: Using Doppler for configuration

# Set custom Claude directory via Doppler
doppler secrets set CLAUDE_DIR /custom/path/.claude

# Run server with Doppler secrets
doppler run -- bun run start

Workflow

The recommended workflow for using this MCP server:

1. Start with list_projects - Discover available projects
2. Use list_sessions - Browse sessions with optional date filtering
3. Get detailed history with get_conversation_history - Retrieve full conversations with pagination
4. Search with search_conversations - Find specific topics across all conversations

Troubleshooting

"No projects found"

• Ensure CLAUDE_DIR is set correctly
• Check that the directory exists and contains project subdirectories
• Try get_config to verify your configuration

Doppler authentication issues

# Verify Doppler is authenticated
doppler me

# Check available projects
doppler projects

# Verify secrets are set
doppler secrets list

Large response sizes

• Use messageTypes: ["user"] to reduce data volume (default)
• Use limit parameter for pagination
• Use date range filters to narrow results

Dependencies

This package requires the following workspace dependencies:

• @ebowwa/claudecodehistory - Core Claude Code history service library

License

MIT

Author

ebowwa