mcp-claude-logs

MCP (Model Context Protocol) server for parsing and exposing Claude Code session logs with auto-sync to dashboard.

Features

• Session Listing: List all Claude Code sessions with metadata
• Session Details: Get full conversation history with tool calls
• Statistics: Aggregate token usage, costs, and tool usage
• Auto-Sync: Automatically sync sessions to dashboard when file changes detected
• Dashboard Integration: Sync sessions to external dashboard API

Installation

As MCP Server (Recommended)

Add to your Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "claude-logs": {
      "command": "npx",
      "args": ["mcp-claude-logs"],
      "env": {
        "DASHBOARD_URL": "http://localhost:4001"
      }
    }
  }
}

Global Installation

npm install -g mcp-claude-logs

Configuration

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | DASHBOARD_URL | Dashboard API URL for auto-sync | Optional |

When DASHBOARD_URL is set, the server automatically syncs sessions when file changes are detected in ~/.claude.

Config File (Alternative)

Create ~/.claude-dashboard.json:

{
  "apiUrl": "http://localhost:4001",
  "apiToken": "your-jwt-token"
}

Available MCP Tools

list_sessions

List Claude Code sessions with optional filters.

Parameters:

• project (string, optional): Filter by project path
• startDate (string, optional): Filter by start date (ISO 8601)
• endDate (string, optional): Filter by end date (ISO 8601)
• limit (number, optional): Max sessions to return (default: 50)

get_session

Get detailed session information including conversation.

Parameters:

• sessionId (string, required): Session ID
• projectPath (string, optional): Project path for faster lookup

get_conversation

Get conversation messages for a session.

Parameters:

• sessionId (string, required): Session ID
• projectPath (string, optional): Project path
• includeToolResults (boolean, optional): Include tool results (default: false)

get_stats

Get aggregated statistics across sessions.

Parameters:

• project (string, optional): Filter by project
• startDate (string, optional): Start date
• endDate (string, optional): End date

sync_to_dashboard

Manually sync sessions to dashboard.

Parameters:

• sessionId (string, optional): Sync specific session
• limit (number, optional): Max sessions to sync (default: 50)
• since (string, optional): Only sync sessions after this date

CLI Commands

# Start MCP server (default)
npx mcp-claude-logs

# Or with serve command
npx mcp-claude-logs serve

# Manual sync
npx mcp-claude-logs sync

# Show help
npx mcp-claude-logs help

Auto-Sync Architecture

When DASHBOARD_URL is configured:

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Claude Code     │     │  MCP Server      │     │  Dashboard API   │
│                  │     │                  │     │                  │
│  ~/.claude/      │────▶│  FileWatcher     │────▶│  /sync/local     │
│  projects/*.jsonl│     │  (debounce 500ms)│     │                  │
└──────────────────┘     └──────────────────┘     └──────────────────┘

• FileWatcher monitors ~/.claude for .jsonl file changes
• Debounce prevents excessive API calls (500ms)
• Sessions are synced to dashboard without authentication (local mode)

Programmatic Usage

import { listSessions, getSession, syncToDashboard } from 'mcp-claude-logs/tools';
import { loadFullSession } from 'mcp-claude-logs/parsers';

// List recent sessions
const sessions = await listSessions({ limit: 10 });

// Get full session with conversation
const session = await getSession({ sessionId: 'abc-123' });

// Sync to dashboard
const result = await syncToDashboard({
  apiUrl: 'http://localhost:4001',
  limit: 5
});

License

MIT