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

npm install claude-telemetry-mcp

Configuration

Add to your Claude Code MCP configuration:

{
  "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

// 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

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

Personal Trend Analysis

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

Tool Usage Insights

// 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