# Claude Telemetry MCP

Model Context Protocol (MCP) server for tracking Claude Code usage patterns, personal trends, and allowance limit monitoring.

## Overview

This MCP server helps you understand your personal Claude Code usage by tracking session metrics, analyzing usage trends, and monitoring against allowance limits. Get insights into your workflow patterns, tool usage habits, and stay aware of usage boundaries.

## Features

### Personal Usage Tracking
- Session usage monitoring (tokens, costs, activity duration)
- Daily and weekly usage summaries
- Personal usage trend analysis over time
- Tool usage pattern insights and frequency analysis

### Allowance Management
- Usage limit monitoring with configurable thresholds
- Proactive warnings before approaching limits
- Remaining capacity estimation based on current trends
- Historical usage comparison for planning

### Analytics & Insights
- Session analytics and productivity patterns
- Tool usage breakdown and effectiveness metrics
- Usage trend analysis for better workflow planning
- Capacity forecasting based on historical data

## Installation

```bash
npm install claude-telemetry-mcp
```

## Configuration

Add to your Claude Code MCP configuration:

```json
{
  "mcpServers": {
    "claude-telemetry": {
      "command": "node",
      "args": ["path/to/claude-telemetry-mcp/build/index.js"]
    }
  }
}
```

## Available Tools

### Current Usage
- `get_current_session_usage` - Get current session metrics and token consumption
- `get_today_usage` - Get today's usage summary and trends
- `get_week_usage` - Get weekly usage metrics and patterns

### Usage Analysis
- `get_usage_summary` - Comprehensive usage overview with personal insights
- `get_usage_trends` - Analyze personal usage patterns over time
- `get_session_analytics` - Session pattern analysis and productivity insights
- `get_tool_usage_breakdown` - Tool usage statistics and preferences

### Limit Management
- `check_usage_limits` - Monitor usage against specified allowance limits
- `get_usage_warnings` - Get threshold warnings and limit notifications
- `estimate_remaining_capacity` - Calculate remaining allowance capacity
- `compare_usage_periods` - Compare usage between different time periods

### System Health
- `get_telemetry_health` - Check telemetry system status and data quality

## Usage Examples

### Monitor Daily Progress
```typescript
// Check today's usage against your patterns
const todayUsage = await client.callTool("get_today_usage", {});
console.log(`Today: ${todayUsage.tokens} tokens (${todayUsage.trend})`);
```

### Allowance Limit Monitoring
```typescript
// Check if approaching monthly limits
const limits = await client.callTool("check_usage_limits", {
  monthly_token_limit: 100000,
  daily_session_limit: 50
});
```

### Personal Trend Analysis
```typescript
// Analyze your usage patterns
const trends = await client.callTool("get_usage_trends", {
  period: "last_30_days",
  include_predictions: true
});
```

### Tool Usage Insights
```typescript
// See which tools you use most
const toolStats = await client.callTool("get_tool_usage_breakdown", {
  timeframe: "week",
  include_efficiency_metrics: true
});
```

## Personal Analytics Features

### Usage Pattern Recognition
- Peak usage times and productive periods
- Session duration and break patterns
- Tool preference and workflow insights
- Weekly and monthly rhythm analysis

### Limit Management
- Proactive notifications before limit thresholds
- Usage velocity tracking (tokens per hour/day)
- Remaining allowance projections
- Historical limit breach analysis

### Productivity Insights
- Most productive time periods
- Tool usage effectiveness metrics
- Session efficiency and focus patterns
- Workflow optimization suggestions

## Benefits

- **Stay Within Limits**: Proactive monitoring prevents unexpected limit hits
- **Understand Patterns**: Learn your most productive usage patterns
- **Optimize Workflow**: Identify which tools and times work best for you
- **Plan Usage**: Forecast and budget your Claude Code usage effectively
- **Track Progress**: Monitor your development productivity over time

## Privacy & Data

- All data is stored locally on your machine
- No usage data is transmitted to external services
- You have full control over data retention and deletion
- Telemetry focuses on usage patterns, not content analysis

## License

MIT