@mcp/claude-code-history

MCP server for accessing Claude Code conversation history with Doppler integration.

Features

• List Projects: Discover all Claude Code projects in your Claude directory
• List Sessions: Browse conversation sessions within each project with date filtering
• Get History: Retrieve paginated conversation history with flexible filtering
• Search: Full-text search across all conversations with date and project filters
• Doppler Integration: Manage configuration via Doppler environment variables

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